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Parti: U ser Commands 

Introduction 

This section introducesand describesuser commands. 
AUTHORS 

Look at theheader of themanual page for the author(s) and copyright conditions. N otethat thesecan bedifferent from page 
to page. 

addftinfo 

addftinfo— Add informati on totroff font filesfor usewith groff 
SYNOPSIS 

addftinfo [ -paramvalue . . . ] res uni t wi d t h font 

D ESC RIPTIO N 

addftinfo readsatroff font file and adds some addi ti onal font-metric information that isused by the groff system. The font 
filewith the information added iswritten on the standard output. The information added isguessed usi ng some parametric 
information about thefontand assumptionsaboutthetraditional troff namesforcharacters. Themain information added 
istheheightsand depthsof characters. The res and unitwidtn argumentsshould bethesameasthecorresponding param- 
eters in the desc fi le; font is the name ofthef ile describi ng the font; if font endswith I, the font wi II beassumed to beitalic. 

OPTIONS 

Each of the f optionschangesoneof the parameters that isused to derive the heights and depths. L ike the existing quanti ties 
in thefontfile, each value isin inches/resforafontwhosepoint sizeis unitwidtn. param must beone of the following: 



x-height 


Theheight of lowercaseletterswithout ascenders such asx 


fig-height 


The height of figures (digits) 


asc-height 


The height of characters with ascenders, such as b, d, or 1 


body-height 


The height of characters such as parentheses 


cap-height 


Theheight of uppercasel etters su eh as A 


comma -deptn 


Thedepth of a comma 


desc-depth 


Thedepth of characters with descenders, such asp, q, or y 


body-depth 


Thedepth of characters such as parentheses 



addftinfo makes no atterri pt to use the speci fi ed parameters to guesstheunspecified parameters. If a parameter is not 
specifi ed, the default will beused. Thedefaultsarechosen to havethereasonablevalues for a Times font. 

SEEALSO 

font(5) groff _font(5), groff(l), grof f_char(7) 

Groff Version 1.09, 6 August 1992 

afmtodit 

afmtodit- Create font filesfor use with groff -Tps 
SYNOPSIS 

afmtodit [ -ns ] [ — dd esc fi I e ] [ -ee n c _f i I e ][-in ][-an ] a f m_ file ma p _f i I e font 



afmtodit 



DESCRIVO N 

afmtodit creates a font filefor usewith groff and grops. afmtodit iswritten in Perl; you must havePerl version 3 installed in 
order to run afmtodit. afm_fiie istheAFM (Adobe Font M etric) filefor the font. map_fiie isafilethat sayswhich groff 
character namesmap onto each PostScript character name; thi s file should contai n asequenceof linesof the forni: 

p s _ c h a r groff_char 

whereps^char is the PostScript name of the character and groff_char is the groff name of the character (asused in the groff 
font file) The sameps_char can occur multi pie ti mes in the file; each groff _char must occur, at most, once, font is the groff 
name of the font. If a PostScript character is in the encoding to beused for the font but isnot mentioned in map_fiie, then 
afmtodit will put it in the groff font file as an unnamed character, which can beaccessed by the \n escape sequence i n troff. 
Thegroff_font fi le wi 1 1 be output to afilecalled font. 

If there is a downloadable font filefor the font, it may belisted in thefile/usr/iib/groff/font/devps/downioad; seegrops(l). 

If the-i option isused, afmtodit will automati cai ly generate an italic correction, a left italic correction, and a subscript 
correction for each character (the significance of these parameters isexplained in groff_font(5)); theseparametersmay be 
specified for individuai characters by adding to theafm_fiie linesof the form: 

italicCorrectionps charn 
leftltalicCorrectionps charn 
subscriptCorrectionps charn 

wherepschar is the PostScript name of the character, and n is the desi red valueof thecorresponding parameter in thou- 
sandthsof an em. These parameters arenormally needed only for italic (or oblique) fonts. 

OPTIONS 

-n Don't output a ligaturescommand for this font. Usethiswith constant-width fonts. 

-s The font is special. The effect of this option isto add the special command to the font file. 

-ddesc.fi i e T he device descri ption fileisdesc_f i i e rather than the default desc. 

-eencj m e The PostScript font should bereencoded to use the encoding descri bed in enc.fi i e. The format of 

enc.f i I e isdescribed in grops(l). 

-an Usen asthe slant parameter in thefontfile; thisisused by groff in the positioning of accents. By 

default, afmtodit uses the negative of the itaiicAngie specified in theaf m.f m e; with true italic 
fonts, it issometi mes desi rableto use a slant that islessthan this. If you find that characters from 
an italic font have accents placed too farto theright over them, then usethe-a option to givethe 
font a smaller slant. 

-in Generate an italic correction for each character so that the character'swidth plus the character's 

italic correction isequal to n thousandthsof an em plus the amount by which therightedgeof the 
character's bounding isto theright of the character's ori gin. If thiswould result in a negative italic 
correction, useazero italic correction instead. 

Also generate a subscri pt correction equal to the product of the tangent of the slant of the font and 
four-fifthsof the x-heightof the font. If thiswould result in a subscript correction greater than the 
italic correction, use a subscript correction equal to the italic correction instead. 
Also generate a left italic correction for each character equal to n thousandthsof an em plus the 
amount by which the left edge of the character's bounding box is to the left of the character's 
origin. The left italic correction may be n egati ve. 

This option isnormally needed only with italic (or oblique) fonts. The font files distri buted with 
groff werecreated usingan option of-iso for italic fonts 

FILES 

/usr/iib/groff /font/devps/DEsc D evi cedescri ption file 

/usr/iib/groff/font/devps/F Font description filefor font F 

/usr/lib/groff/font/devps/download List Of downloadable fonts 
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/usr/iib/groff /font/devps/text.enc Encoding used for text fonts 

/usr/lib/groff/font/devps/generate/textmap Standard mapping 

SEEALSO 

groff(l), grops(l), groff_font(5), perl(l) 

GroffVersion 1.09, 14 February 1994 

ansi2knr 

ansi2knr— ConvertANSI C to Kernighan Si RitchieC 
SYNOPSIS 

ansi2knr t n p u t _ f i I e outputjile 

D ESC RIPTIO N 

If no out put.f il e is supplied, output goesto stdout. Thereareno errar messages. 

ansì2knr recognizesfunctions by seeing a nonkeyword i dentiti er at theleft margin, followed by a left parenthesis, with a right 
parenthesis as the last character on the line. It will recognize a multi line header if thelast character on each linebut thelast is 
a left parenthesis or comma. T hese algorithms ignore whitespace and comments, except that the function name must be the 
first thing on theline. 

T he followi ng constructs will confuse i t: 

■ Any other construct that startsat theleft margin and followstheabovesyntax (such asa macro or function cali) 

■ M acrosthattinkerwith thesyntaxof thefunction header 

31 Decemberl990 

anytopnm 

anytopnm— Attempt to convert an unknown typeof imagefileto a portableanymap 
SYNOPSIS 

anytopnm file 

DESCRIPTION 

anytopnm uses the fi le program, possi bly augmented by the magic numbersfileincluded with pbmplus, to try to figure out 
what typeof imagefileit is. If that fai Is (very few imageformats have magic numbers), looksatthefilenameextension. If 
thatfails, punt. 

T he type of the output fi le depends on the input file 
SEEALSO 

pnmfile(l), pnm(5), file(l) 

BUGS 

It's a script. Scripts are not portableto non-U N IX environments. 

AUTHOR 

C opyright © 1991 by J ef Poskanzer 

27 July 1990 
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appres 

appres— List x application resource database 
SYNOPSIS 

appres [[class [instance]] [-1] [tool ki topti ons ] 

DESCRIVO N 

The appres program printstheresourcesseen by an application (orsubhierarchy of an application) with the specified class 
and instancenames. It can beused to determi ne which resourcesa parti cular program will load. For example, 

% appres XTerm 

will list the resourcesthat any xterm program will load. If no application class is specified, the class -AppResTest- isused. 

To match a particular instance nam e, specify an instance nameexpli ci tly after the class nam e, or usethenormal xt toolkit 
option. For example, 

% appres XTerm myxterm 

or 

% appres XTerm -name myxterm 

To list resourcesthat match asubhierarchy of an application, specify hierarchical class and instancenames. Thenumber of 
class and instancecomponentsmust beequal, and the instance name should not be specified with atoolkit option. For 
example, 

% appres Xman .TopLevelShell. Form xman . topBox.f orm 

will listtheresourcesof widgetsof xman topBox hierarchy. To list just the resources matching aspecific level in thehierarchy, 
usethe-1 option. For example, 

% appres XTerm. VT100 xterm. vt100 -1 

will list the resources matching thexterm vtm widget. 
SEEALSO 

x(l), xrdb(l), listres(l) 

AUTHOR 

J im Fulton (M IT X C onsortium) 

X Versi on 11 Release6 



ar 

ar— Create, modify, and extractfrom archives 
SYNOPSIS 

ar [ - ] dmpqrtx[abcilosuvV] [ membername ] archi ve files ... 

DESCRIPTION 

TheGN U ar program creates, modifies, and extractsfrom archives. An archi ve is a single fi le holding a collection of other 
files in astructurethat makes it possi bleto retri ève the originai individuai fi les (called membersof thearchive). 

The originai files' contents, mode (pernii ssions), timestamp, owner, and group arepreserved in thearchive, and may be 
reconstituted on extraction. 
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GN U ar can mai ntain archi veswhosemembers have names of any length; however, dependi ng on how ar isconfigured on 
your system, a limit on member-name length may beimposed (for compati bili ty with archi ve formats maintained with other 
tools). If itexists, the limit isoften 15 characters (typical of formats related to a. out) or 16 characters (typical of formats 
related to coff). 

ar isconsidered a binary utility because archi vesof thissortaremostoften used aslibrariesholdingcommonly needed 
subroutines. 

ar wi II create an index to thesymbolsdefined in relocatable object modules in the archi ve when you speci fy themodifier s. 
Oncecreated, this index isupdated in thearchivewhenever ar makesachangeto itscontents(savefor theq update 
operati on). An archivewith such an index speedsup linking to the library, and allowsroutinesin the library to cali each 
otherwithout regard to their placement in thearchive. 

You may use nm -s or nm -print-armap to I ist this index table. If an archive lacks thetable, anotherform of ar called raniib 
can beused to add just thetable. 

ar insistson at least two argumentsto execute: onekeyletter specifying the operati on (optionally accompanied by other 
keyletters specifying modifiers), and the archive nameto act on. 

M ost operationscan also accept further filesarguments, specifying particular fi lesto operate on. 
OPTIONS 

GN U ar allowsyou to mixtheoperation codep and modifier flagsmod in any order, within the first command-line 
argument. 

If you wish, you may begin the first command-line argument with a dash. 

The p keyletter specifies what operation to execute; itmaybeanyofthefollowing, butyou must specify onlyoneof them: 

d Delete modules from thearchive. Specify the names of modules to bedeleted as fi les; the archive is 

untouched if you specify no fi lesto delete. 

If you specify the v modifier, arwill list each moduleasit isdeleted. 
m Use this operation to movemembers in an archive 

Theorderingof membersin an archive can makeadifferencein how programsarelinked usingthe 

library if a symbol is defi ned in morethan onemember. 

If no modifiers are used with m, any membersyou namein the filesarguments aremoved to the end of 

thearchive; you can usethea, b, ori modifiers to move them to aspecified place instead. 
p Pri nt the specified membersof the archive to the standard output fi le. If the v modifier is specified, 

show the membername before copying its contents to standard output. 

If you specify no files, ali the fi les in the archive are pri nted. 
q Quick append; add fi lesto the end of archi ve without checkingfor replacement. 

The modifiers a, b, and i do not affect this operation; new membersarealways placed at the end of the 

archive. 

Themodifier v makesar list each fileasit isappended. 

Sincethepoint of this operation isspeed, the archi ve's symbol table index isnot updated, even if it 
already existed; you can usear s or raniib explicitly to update the symbol table index, 
r I nsert fi les i nto archive (with replacement). This operation differs from q in that any previously existing 

members are deleted if their names match those bei ng added. 

If oneof thefilesnamed in files doesn't exist, ar displaysan errar messageand leavesundisturbed any 
existing membersof the archive matching that name 

By default, new members are added at the end of the fi le, butyou may use oneof the modifiers a, b, or 
ito request placement relati veto some existing mem ber. 

Themodifier v used with this operation eli ci ts a lineof output for each fileinserted, along with oneof 
the letters a or r to indicate whether the filewas appended (no old member deleted) or replaced. 



t D i splay a table listi ng the contentsof archivi or thoseof the files listed in filesthat arepresent in the 

archi ve. N ormally, only themembernameisshown; if you also wantto seethemodes(permissions), 
timestamp, owner, group, and size, you can request that by also specifying thev modifier. 
If you do not specify any files, ali filesin the archi ve are listed. 

If thereis morethan onefilewith thesamename(say, ne) in an archi ve (say, b.a), ar t b.a fie will 
list only the fi rst instane? to seethem ali, you must ask for a compi eteli sting— in our example, ar t 

b.a. 

x Extract members(named files) from the archi ve. You can use thev modifier with thisoperation to 

request that ar list each name as it extraets it. 
If you do not specify any files, ali filesin the archi ve are extracted. 

A number of modifiers(mod) may immediately follow thep keyletter, to specify variationson an operation'sbehavior, as 
follows: 

a Add new files after an existing member of the archi ve. If you use the modifier a, the name of an 

exi sti n g arch i ve m em ber m ust be present as th e m em bern am e argu m en t, bef ore th e arch i ve speci fi ca- 
tion. 

b Add new files beforean existing member of thearchive. If you use the modifier b, the name of an 

exi sti n g arch i ve m em ber m ust be present as th e m em bern am e argu m en t, bef ore th e arch i ve speci fi ca- 
tion (sameasi). 

c C reate the archi ve. The specified archiveisalwayscreated if it didn't existwhen you request an update. 

But a warning isissued unlessyou specify in advance that you expect to create it by using this modifier. 
i Insert new files beforean existing member of thearchive If you use the modifier i, the name of an 

exi sti n g arch i ve m em ber m ust be present as th e m em bern am e argu m en t, bef ore th e arch i ve speci fi ca- 

tion. (sameasb). 
1 This modifier isaccepted but not used. 

o Preserve the originai datesof memberswhen extractingthem. If you do not specify this modifier, files 

extracted from the archi ve will bestamped with the ti me of extraction. 
s Writean object-fi le index into thearchive or update an existing one, even if no other changeismade 

to thearchive. You may use this modifier flageither with any operation, or alone. Runningar s on an 

archiveisequivalentto running raniib on it. 
u N ormally, ar r... insertsall files listed into thearchive. If youwould liketo insert only thoseof the 

files you list that arenewer than existing membersof thesamenames, use this modifier. Theu modifier 

isallowed only for the operation r (replace). In parti cular, thecombination qu isnotallowed, since 

checkingthetimestampswould loseany speed advantagefrom theoperation q. 
v This modifier requests the verbose version of an operation. M any operations di splay additional 

information, sucn asfilenames processed, when the modifier v isappended. 
v This modifier shows the version number ofar. 

SEE ALSO 

binutiis entry in info; TheGN U Binary Utilities, Roland H . Pesch (October 1991); ™(1), aniib(l) 
COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. Permission isgranted to copy 
and di stri bute modified versionsof this manual under the condì tions for verbatim copying, provided that the enti re resulti ng 
derived work is distri buted under the termsof a permission noticeidentical to this one. 

Permission isgranted to copy and distri bute translati onsof this manual into another language under the above condì tions 
for modified versi ons, except that this permission noticemay beincluded in translationsapproved by the Free Software 
Foundation instead of in theoriginal English. 

CygnusSupport, 5 N ovember 1991 
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arch 

arch— Print archi tecture 
SYNOPSIS 

arch 

D ESC RIFTIO N 

arch displays machi ne architetture type. 

SEEALSO 

uname(l), uname(2) 

Debian GNU/Linux, 15 January 1994 



GNU as 

GNU as-TheportableGNU assembler 
SYNOPSIS 

as [ -a -al j -as ][-D ][-f ][-I p a t h ][-K ][-L ][-o objfile ][-R ][-v ][-w ][— \\\ 
f i I e s . . .] 

i960-only options 

[ -ACA| -ACA A | -ACB | -ACC -AKAj -AKB | -AKC ] -AMC][-b ][-no-relax ] 

m680x0-only options: 

[ -1 ] [-mc68000 | -mc68010| -mc68020] 

DESCRIPTION 

GN U as i s really a fami ly of assemblers. If you use (or haveused) theGN U assembler on onearchitecture, you should find a 
fairly similarenvironmentwhen you useiton anotherarchitecture. Each version hasmuch in common with theothers, 
including object file formats, most assembler di recti ves(often called pseudo-ops) and assembler syntax. 

For information on the syntax and pseudo-ops used by GN U as, seeas entry in info (orthemanual Usingas TheGN U 
Assembler). 

as is pri mari ly i ntended to assemble the output of theGN U C compi lergcc for useby thelinker id. N evertheless, we'vetried 
to makeas assemble co rrectly everythingthat the nati ve assembler would. Thisdoesn't mean as alwaysuses the same syntax 
asanother assembler for the same architecture; for example, we know of several i ncompatible versi onsof 680x0 assembly 
language syntax. 

Each timeyou run as, it assemblesexactly onesource program. The source program ismadeup of oneor morefiles. (The 
standard input is also a fi le.) 

If as isgiven no filenames, it attemptsto read oneinputfilefrom theas standard input, which isnormally your terminal. 
You may haveto typeCtrl-D to teli as thereisno more program to assemble. U se — if you need to explicitly namethe 
standard input file in yourcommand line. 

as may writewarningsand error messagesto the standard errar fi le (usuai ly your terminal). This should not happen when as 
isrun automati cally by a compi ler. Warningsreport an assumption madeso that as could keep assembling aflawed program; 
errors report a grave problem that stops the assembly. 
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OPTIONS 

-a|-ai|-as Tum on assembly listings; -ai, listing only, -as, symbolsonly, -a, everything. 

-D Thisoption isaccepted only for script compati bili tywith Calisto other assemblers; it 

has no effect on as. 

-f "Fast"-skip preprocessing(assumesourceiscompileroutput). 

-npath Add path tothesearch list for .include di rectives. 

-k Issuewarningswhen differencetables altered for long displacements. 

-l Keep (in symbol table) locai symbols, startingwith L. 

-o\o bj f i i e N ame the object-fi le output from as. 

-R Fold data section into text section. 

-v Announceas version. 

-w Suppresswarning messages. 

— \|\f i i es .. . Sourcefilesto assemble, or standard input (— ). 

-Avar (W hen configured for Intel 960.) Specify which variant of the 960 architectureisthe 

target. 

-b (W hen configured for Intel 960.) Add codeto collect statisti cs about branchestaken. 

-no -relax (W hen configured for Intel 960.) Do not alter compare-and-branch instructionsfor 

long displacements; errar if necessary. 
-ì (W hen configured for M otorola 68000.) Shorten referencesto undefined symbols to 

oneword instead of two. 

-mc68000|-«ic680i0|-mc68020 (W hen configured for M otorola 68000.) Specify which processor in the 68000 

family is the target (default 68020). 



Optionsmay bein any order, and may be before, after, or between filenames. Theorder of fi lenamesis signi ficant. 

The doublé hyphenscommand (-) by itself names the standard input fileexplicitly, asoneof thefilesfor as to assemble. 

Exceptfor —, any command lineargument that beginswith a hyphen (-) isan option. Each option changesthebehavior of 
as. N 0 option changestheway another option works. An option is a hyphen followed by oneor moreletters; the case of the 
letter is i mportant. Ali options are optional. 

The-o option expectsexactly onefilenameto follow. Thefilenamemay either immediately follow th e option's letter 
(compati blewith older assemblers) or it may bethenext command argument(GN U standard). 

Thesetwo command li nes are equivalenti 

as -0 my-object-file.o mumble.s 
as -omy-object-file.o mumble.s 

SEEALS0 

as entry in info; Using as: TheGN U Assembler; gcc(l), id(l). 
C0PYING 

Copyright © 1991, 1992 F ree Software Foundation, Inc. Permission isgranted to makeand distribute verbatim copiesof 
thismanual provided the copyright noticeand this permission noticearepreserved on ali copies. Permission isgranted to 
copy and distribute modifi ed versionsof thismanual under the conditions for verbatim copying, provided that the enti re 
resulting derived work is distri buted under the termsof a permission noticeidentical to thisone. 

Permission isgranted to copy and distri bute translati onsof thismanual into another language, under the above conditions 
for modifi ed versi ons, except that this permission noticemay beincluded in trans! ationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

CygnusSupport, 21 January 1992 
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asciitopgm 

asciitopgm— C onvert ASC 1 1 graphi cs i nto a portable graymap 
SYNOPSIS 

asciitopgm [-d divisori h e i g h t width [asci i fi I e ] 

D ESC RIPTIO N 

Reads ASC 1 1 data as input. Produce a portable graymap with pixel valuesthat arean approximation of thebrightnessof the 
ASCII characters, assuming black-on-whiteprinting. In other words, a capital M isvery dark, a peri od isvery light, and a 
space iswhi te. Input linesthat arefewer than width characters are automatically padded with spaces. 

The di vi sor argument isafloating-point number by which the output pixels are divided; the default valueisi .0. Thiscan be 
used to adjust thebrightnessof the graymap; for example, if theimageistoo dim, reduce the di visor. 

In keepingwith (I beli ève) FORTRAN line-printer conventi ons, input li nes beginning with a + (plus) characterareassumed 
to overstri ke the previous line, allowing a larger rangeof gray values. 

Thistool contradictsthemessagein thepbmtoascii manual: "N otethat there is no asciitopbm tool— thistransformation is 
one-way." 

BUGS 

Thetableof ASC II -to-gray values issubject to interpretati on, and, of course, dependson thetypefaceintended for the input. 
SEEALSO 

pbmtoascii(l), pgm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb^usc.edu) 

26 Decemberl994 

atktopbm 

atktopbm— Convert Andrew Toolkit raster object to portable bitmap 
SYNOPSIS 

atktopbm [at kf i I e ] 

DESCRIPTION 

atktopbm readsan Andrew Toolkit raster object as input and produces a portable bitmap as output. 
SEEALSO 

pbmtoatk(l), pbm(5) 

AUTHOR 

Copyright© 1991 by Bill Janssen 

26 September 1991 
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bash— GNU Bourne-again shell 
SYNOPSIS 

bash [opti ons ] [file] 

DESCRIVO N 

bash isan sh-compatiblecommand languageinterpreterthat executescommandsread from the standard input or from a file, 
bash also incorporatesuseful featuresfrom theKorn and C shells (ksh and csh). 

bash is ulti mately intended to beaconformant implementation of thelEEE POSIX Shell and Tools speci fication (IEEE 
Working Group 10032). 

OPTIONS 

In additi on to the si ngle-character shell optionsdocumented in thedescription of the set built-in command, bash interprets 
thefollowing flagswhen itisinvoked: 

-c st ri ng If the -c flag ispresent, then commandsareread from stri ng. If there are arguments after the 

stri ng, they are assi gned to the posi tional parameters, starti ng with $0. 
-i If the-i flag ispresent, theshell isinteractive. 

-s If the-s flag ispresent, or if no arguments remai n after option processing, then commandsare 

read from thestandard input. Thisoption allows the positi onal parameters to besetwhen 
invokingan interacti ve shell. 

A single- signalstheend of optionsand disablesfurther option processing. Any arguments after 
the - aretreated asfilenamesand arguments. An argument of - isequivalent to an argument 
of-. 

bash also interprets a numberof multicharacter options. To berecognized, theseoptionsmust appearon the command line 
before the si ngle-character options. 

-norc Do not read and execute the personal initialization file "/.bashrc if theshell isinteractive. This 

option ison by default if theshell isinvoked assh. 

-noprofiie Do not read either the system- wi de startup file /etc/pronie or any of the personal initializa- 

tion files 7.bash_profiie, " / . bash_iogin, or '/.prof ile. By default, bash normally reads these 
fileswhen it isinvoked asalogin shell. (Seethe"lnvocation" section, later in thismanual page.) 

-retile file Execute commands from fi le i nstead of the standard personal initialization file - /, bashrc, if the 

shell isinteractive. (See"lnvocation.") 

-version Show the version num ber of this instanceof bash when starting. 

-quiet Do not be verbose when starti ngup (do not show theshell version or any other informati on). 

This is the default. 

-ìogin M akebash act as i f it had been invoked asa login shell. 

-nobraceexpansion Do not perform curly brace expansion. (See"BraceExpansion," later in thismanual page.) 

-noiineediting D o not use the G N U readiine library to read command linesif interacti ve. 

-posix C hange the behaviorof bash where the default operati on differs from the POSIX 1003.2 

standard to match thestandard. 

ARGUMENTS 

If arguments remai n after option processing, and neither the -e nor the-s option hasbeen supplied, thefirst argument is 
assumed to be the nameof a file contai ni ng shell commands. If bash isinvoked in this fashion, issetto thenameof thefile, 
and the positional parameters are setto the remaining arguments. bash reads and executes commands from thisfile, then 
exits. bash's exit status is the exit status of the last command executed in the script. 
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DEFINITIONS 

blank 
word 
name 

meta character 
control operato r 

RESERVED WORDS 

Reserved wordsarewordsthat have a special meaning to the shell . T he followi ng words are recognized asreserved when 
unquoted and either the first word of asimplecommand (see "Shell Grammar," next) orthethird word of acaseorfor 
command: 

! case do done elif else esac fi for function if in select then until while { } 

SHELL GRAMMAR 
SIMPLE COMMANDS 

A si mple command is a sequenceof optional variableassignmentsfollowed by words and redi recti onsseparated by blank and 
termi nated by a control operator. The first word specifies the command to beexecuted. The remai ning words are passed as 
argumentsto theinvoked command. 

The return valueof asimplecommand isits exit status, ori28+n if thecommand isterminated by signal n. 
PIPELINES 

A pipe! ine is a sequenceof oneor more commands separated by the character |. The format for a pi peli nei s 

[ ! Jcommand [ j command 2 ... ] 

The standard output of command isconnected to the standard input of comma nd 2. This connection is performed beforeany 
redi recti onsspecified by thecommand. (See the "Redirection" section, later in this manual page.) 

If the reserved word ! precedes a pipel i ne, the exit status of that pi peli ne i s the logi cai not of the exit status of the last 
command. Otherwise, the status of the pi peli ne is the exit status of the last command. The shell waitsfor ali commands in 
the pipeline to terminate before returning a value. 

Each command in a pipeline isexecuted as a separate process (that is, in asubshell). 
LISTS 

A list is a sequenceof oneor more pi peli nes separated by oneof these operato rs: ;,&,&&, or | j, and termi nated by oneof 

these: ;, &, Or <newline>. 

Of these list operators, && and ì ì haveequal precedence, followed by ; and &, which haveequal precedence. 

If a command isterminated by the control operators., the shell executes the command in the background in a subshell. The 
shell does not wait for thecommand to finish, and the return status is 0. Commands separated by a ; areexecuted sequen- 
tially; the shell waitsfor each command to terminate in turn. The return status is the exit status of the last command 
executed. 

Thecontrol operators && and | \ denote and listsand or lists, respectively. An and list hastheform: 

command && comma n d 2 

command2 isexecuted if, and only if, command returnsan exit status of zero. 



A space or tab. 

A sequence of charactersconsidered as a single unit by the shell. Also known asatoken. 
A word consisti ng only of alphanumeric characters and underscores and beginning with an 
alphabetic character or an underscore. Also referred to asan identifier. 
A character that, when unquoted, separates words. 0 ne of the followi ng: 

|, & , ;, (, ), <, >, space tab 
A token that performs a control function. It is oneof the followi ngsymbols: 

||,&,&&,;, ;;, (, ), |, <newline> 




An or list has the forni 

command command2 

command2 isexecuted if, and only if, command returns a non-zero exit status. The return status of and and or listsis the exit 
status of the last command executed in the list. 

COMPOUND COMMANDS 

A compound command isoneof thefollowing: 
(list) 

list isexecuted in asubshell. Variableassignmentsand built-in commandsthat affecttheshell'senvironmentdo not remai n 
in effect after the command completes. The return status is the exit status of list. 

{list; } 

list issimply executed in thecurrent shell environment. Thisisknown asagroup command. The return status is the exit 
status of i i s t . 

f or nane [ in word;] do list ; done 

The list of wordsfollowi ng in isexpanded, generating a list of items. The vari ablenameis setto each element of this list in 
turn, and li st isexecuted each ti me. If the in word is omitted, the f or command executesi i st once for each positional 
parameterthatisset. (See'Tarameters," later in thismanual page) 

select na me [ in wo r d ; ] do I i s t ; done 

T he list of wordsfollowi ng in isexpanded, generating a list of items. The set of expanded wordsisprinted on the standard 
error.each preceded byanumber. Ifthem word isomitted, the positional parametersareprinted. (See"Parameters.") The 
PS3 prompt isthen displayed and a lineread from the standard input. I f the line consists of the number correspondi ng to 
oneof thedisplayed words, then the valueof nameis setto thatword. If the line is empty, thewordsand prompt are 
displayed again. If eof isread, the command completes. Any other value read causes nameto beset to nuli. The lineread is 
saved i n the variable reply. T he list isexecuted after each selection until a break or return command isexecuted. The exit 
status of seiect is the exit status of the last command executed in list, or zero if no commandswere executed. 

case wo r d in [ pattern [ ] pattern ] 

A case command first expands word, and triesto match it against each pattern in turn, using thesamematching rulesasfor 
pathnameexpansion. (See "Pattinarne Expansion," later in thismanual page.) W hen a match isfound, the correspondi ng list 
isexecuted. After the first match, no subsequent matches are attempted. The exit status is zero if no patterns are match es. 
Otherwise, it is the exit status of the last command executed in i i st . 

if list then list [ elif I i st then list ] ... [ else list ] fi 

The if list isexecuted. If its exit status is zero, the then list isexecuted. Otherwise, each eiit list isexecuted in turn, and if its 
exit status iszero, the correspondi ng then list isexecuted and the command completes. Otherwise, the else list isexecuted, if 
present. The exit status is the exit status of the last command executed, or zero if no condition tested True. 

while list do I i s t done 
until list do I i s t done 

The while command conti nuously executes the do list as long as the last command in i i st returns an exit status of zero. The 
untii command is ideiti cai to the while command, exceptthat the test isnegated; the do list isexecuted as long as the last 
command in list returns a non-zero exit status. T he exit status of the whiie and unta commands isthe exit status of the last 
do list command executed, orzerò if none was executed. 

[ function ] name () { list; > 

T his defines a function named name. The body of the function isthe list of commands between {and }. This list isexecuted 
whenever nameis speci fi ed as the name of a sim pie command. The exit status of a function isthe exit status of the last 
command executed in the body. (See'Tunctions," later in thismanual page.) 
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COMMENTS 

In a noninteractive shell, or an i nteractive shell in which the -o interactive-commerits option to the set bui Iti n isenabled, a 
word beginning with # causesthat word and ali remai ni ng characterson that lineto beignored. An i nteractive shell without 
the -o interactive-comments option enabled doesnot allow comments. 

QUOTING 

Quoting isused to remove the special meaning of certain charactersorwordsto the shell. Quotingcan beusedto disable 
special treatment for special characters, to prevent reserved wordsfrom being recognized assuch, and to prevent parameter 
expansion. 

Each of the meta characters li sted earlier under "Definitions" has special meaning to the shell and must bequoted if it isto 
represent itself. There are three quoting mechanisms: the escape character, single quotes, and doublé quotes. 

A nonquoted backslash (\) is the escape character. It preserves the I iterai valueof thenext character that follows, with the 
exception of <newiine>.lf a \<newiine> pai r appears, and the backslash isnot quoted, the \<newiine> istreated asa line 
continuation; that is, it iseffectively ignored. 

Enclosing characters in single quotes preserves the I iterai valueof each character within the quotes. A single quote may not 
occurbetween single quotes, even when preceded by a backslash. 

Enclosing characters in doublé quotes preserves the literal valueof ali characters within the quotes, with theexception of$, \ 
and \. The characters $ and 1 retai n their special meaning within doublé quotes. The backslash retai ns its special meaning 
only when followed by oneof the following characters: $, ', \ \, or <newiine>.A doublé quote may bequoted within doublé 
quotes by precedi ng itwith a backslash. 

The special parameters* and é> have special meaning when in doublé quotes. (See"Parameters," next.) 
PARAMETERS 

A parameter isan entity that stores values, somewhat likea variablein aconventional programmi ng language. It can bea 
name, a number, or oneof the special characters li sted under "Special Parameters," following. For the shell 's purposes, a 
variable is a parameter denoted by a name. 

A parameter i s set if it hasbeen assigned a value. The nuli stri ng isa valid value 0 nce a variable is set, it may beunset only 
by using theunset built-in command. (See "Shell Built-in Commands," later in this manual page.) 

A variable may be assigned to by a statement of theform: 

n a me = [ v a I ne] 

If vai ne isnot given, the variable is assigned the nuli stri ng. AH values undergo tilde expansion, parameter and variable 
expansion, command substitution, arithmetic expansion, and quote removal. If the variable has its -i attri bute set (see 
deciare in "Shell Built-in Commands") then vai ue issubject to arithmetic expansion even if the $[...] syntax does not 
appear. Word spi itti ng isnot performed, with theexception of "$@ M , asexplained under "Special Parameters." Pathname 
expansion isnot performed. 

PO SITION AL PARAMETERS 

A positional parameter isa parameter denoted by oneor moredigits, other than the single digit 0. Positional parameters are 
assigned from the shell 'sarguments when it isinvoked, and may bereassigned using theset built-in command. Positional 
parameters may not be assigned to with assignment statements. The positional parameters are temporarily replaced when a 
shell function isexecuted. (See'Tunctions," later in thismanual page.) 

When a positional parameter consisti ng of more than a single digit isexpanded, it must beenclosed in braces. (See 
"Expansion," later in thismanual page.) 

SPECIAL PARAMETERS 

T he shell treats several parameters speci al ly. These parameters may only bereferenced; assignment tothem isnot allowed. 
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Expandsto thepositional parameters, starting from one. When theexpansion occurswithin doublé 
quote, it expandsto a singleword with the value of each parameter separated by the first character 
of theiFs special variable. That is, "$*" is equivalere to -$ic$2c. wherec isthefirst character of 
the value of the ifs variable If ifs isnull orunset, the parameters are separated byspaces. 
Expandsto thepositional parameters, starting from one. When theexpansion occurswithin doublé 
quotes, each parameter expandsas a separate word. That is, "$@" isequivalent to "$r"$2" .... 
When there are no positi onal parameters, ■$&■ and $? expand to nothing (in otherwords, they are 
removed). 

Expandsto the numberof positional parameters in decimai. 

Expandsto the status of the most recenti yexecuted foreground pipeline. 

Expandsto thecurrent option flagsasspecified upon invocation, by the set built-in command, or 

thoseset by theshell itself (such asthe-i flag). 

Expandsto the processID of theshell. In a o subshell, it expandsto theprocess ID ofthecurrent 
shell, not the subshell. 

Expands to the process I D of the most recently executed background (asynchronous) command. 
Expandsto thenameof theshell or shell seri pt. T hi s is set at shell initialization. If bash isinvoked 
with afileof commands, is set to thenameof that fi le. If bash isstarted with the-c option, then is 
setto thefirst argument after the stringto be executed, if oneispresent. Otherwise, it is set to the 
pathnameused to invokebash, asgiven by argument zero. 

Expandsto thelast argument to the previous command, after expansi on. Also setto the full 
pathnameof each command executed and placed in theenvironment exported to that command. 



SHELL VARIABLES 

T hefollowing variables are set by the shell : 

The processID of thesheN'sparent. 



PPID 
PWD 

OLDPWD 
REPLY 

UID 

EUID 

BASH 

BASH_VERSION 

SHLVL 

RANDOM 



SECONDS 



LINENO 



T he current working di rectoryas set bythecd command. 

T he previous working di rectory as set by thecd command. 

Setto the line of input read by theread built-in command when no argumentsare 

supplied. 

Expandsto the user ID ofthecurrent user, initialized at shell startup. 
Expandsto the effective user I D ofthecurrent user, initialized at shell startup. 
E xpan ds to th e f u 1 1 path n am e used to i n vo ke th i s i n stan ce of bas h . 
Expandstothe versi o n n um ber of th i s i n stan ce of bash . 
Incremented byoneeach timean instanceof bash isstarted. 
Each timethis parameter is referenced, a random integer is generated. Thesequence 
of random numbersmay be initialized by assigning a value to random. If random is 
unset, itlosesits special properties, even if it issubsequently reset. 
Each timethis parameter isreferenced, thenumber of secondssince shell invocation 
isreturned. If a value isassignedto seconds, the value returned upon subsequent 
references is thenumber of seconds si nce the assignment plus the value assi gned. If 
seconds is unset, itlosesits special properties, even if it issubsequently reset. 
Eachtimethisparameterisreferenced, theshell substitutes a decimai number 
representi ng thecurrent sequential line number (starting with 1) within a script or 
function. W hen not in a script orfunction, the value substituted isnotguaranteed to 
bemeaningful. When in afunction, the value is not the number of the sou ree line 
that the command appearson (that information hasbeen lost by thetimethe 
function isexecuted), butisan approximation ofthenumber of si mple commands 
executed in thecurrent function. If lineno is unset, it loses its special properties, even 
if it issubsequently reset. 
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HISTCMD 



OPTARG 



OPTIND 



HOSTTYPE 



OSTYPE 



The hi story number, or index in the hi story list, of the current command. If histcmd 
isunset, itlosesits special properties, even if it issubsequently reset. 
Thevalueof the last opti on argument processed by thegetopts bui It- i n command. 
(See "Shell Built-in Commands," later in thismanual page). 
Theindexof the next argument to be processed by thegetopts built-in command. 
(See "Shell Built-in Commands.") 

Automati cally set to a string that uniquely describes the type of machine on which 
bash isexecuting. The default issystem-dependent. 

Automatically setto a string that describes theoperating system on which basti is 
executing. The default issystem-dependent. 



Thefollowing variablesareused by the shell . In somecases, bash assigns a default valueto avari able; thesecasesarenoted in 
thefollowing list: 

ifs The internai field separatorthat isused for word spi itti ng after expansion and to split 

lines into wordswith theread built-in command. The default valueis 

<space><tab><newline>. 

path Thesearch path for commands. It isacolon-separated list ofdirectories in which the 

shell looks for commands. (See "Command Execution," later in thismanual page). 
Thedefault path issystem-dependent, and isset by theadministratorwho installs 

bash. A Common value ÌS /usr/gnu/bin: /usr/ locai /bin: /usr/ucb: /bin: /usr/bin:. 

home T he home directory of the current user; the default argument for the ed bui I t-i n 

command. 

cdpath Thesearch pathforthecd command. This isacolon-separated list ofdirectories in 

which the shell looks for desti nati on di rectories specified bythecd command. A 
samplevalueis .:~:/usr. 

env If this parameter isset when bash isexecuting a shell script, its value isinterpreted as 

a fi lename contai ni ng commands to i ni ti al ize the shell, asin .bashre. Thevalueof 
env issubjected to parameter expansion, command substitution, and ari thmetic 
expansion before being interpreted asa pathname. path isnot used to search for the 
resultant pathname. 

mail If this parameter is set to a fi lename and the mailpath vari able is not set, bash informs 

theuser of the arrivai of mail in the speci fi ed file. 
mailcheck Specifieshow often (in seconds) bash checksfor mail. Thedefault ÌS60 seconda 

When it isti me to check for mail, the shell doesso before prompting. If this variable 

isunset, theshell disablesmail checking. 
mailpath A colon-separated list of path n amesto becheckedformail.Themessageto be 

printed may be specified by separatingthepathnamefrom themessagewith a 

question mark (?). $_ stands for the nameof the current mailfile. 
Example: 

MAILPATH\ 

= ' /usr/spool/mail/bfox?"You have 
mail" : "/shell-mail?"$_has mail! " 1 

bash supplies a default value for this variable but the location of theuser mail files 
that it uses issystem-dependent (for example, /usr/spooi/maii/$usER). 
If set, and afilethat bash is checking for mail hasbeen accessed sincethe last time it 
waschecked, the message "The mail in mail-fi le hasbeen read" isprinted. 
Thevalueof this parameter isexpanded (see "Prompting," later in thismanual page) 
and used as theprimary prompt string. Thedefault value isbash\$. 
ps2 Thevalueofthisparameterisexpanded and used asthesecondary prompt string. 

Thedefault is>. 



MAIL WARNING 



PS1 
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PS3 



PS4 



HISTSIZE 



HISTFILE 



HISTFILESIZE 



OPTERR 



PROMPT_COMMAND 
IGNOREEOF 



TMOUT 



FCEDIT 
FIGNORE 



INPUTRC 
notify 

history_control HISTCONTROL 

command_oriented_history 
glob_dot_filenames 
allow-null_glob_expansion 
histchars 



T he value of this parameter is used as the prompt for the seiect command. (See 
"Shell Grammar," earlier in thismanual page.) 

Thevalueof this parameter isexpanded and thevalueisprinted beforeeach 
command bash displaysduringan execution trace. The first character of ps4 is 
replicated multi pie ti mes, as necessary, to indicate multiple levelsof indirection. The 
default is+. 

Thenumber of commandsto remember in the command history, (See "H istory," 
later in thismanual page.) Thedefault valueiS5O0. 
Thenameof thefilein which command history issaved. (See"H istory.") The 
default value is _ /.bash_history. If unset, the command history isnot saved when an 
interactive shell exits. 

The maximum number of li nes contai ned in the history fi le. When thisvariableis 
assigned a value, the history fi le is truncated, if necessary, to contain no morethan 
that numberof li nes. Thedefault value is 500. 

If setto the value 1, bash displays errar messages generated by thegetopts built-in 
command. (See "Shell Built-in Commands"). opterr isinitialized to 1 each timethe 
shell is i nvoked or a shell script isexecuted. 

If set, the value isexecuted as a command priorto issuing each primary prompt. 
C ontrolsthe action of the shell on receipt of an eof character as the sole input. If set, 
thevalueis the number of consecutive eof characters typed as the first characterson 
an input line before bash exits. If the vari ableexistsbut doesnot haveanumeric 
value, or hasno value, thedefault value is 10. If it doesnot exist, eof signifies the end 
of input to the shell. This isonly in effect for interactive shells. 
If setto a value greater than zero, thevalue is interpreted as thenumber of seconds 
to wait for input after issuing the primary prompt. bash termi nates after waitingfor 
that number of seconds if input does not arri ve. 
The default editor for the fc built-in command. 

A colon-separated list of suffixes to ignorewhen performingfilenamecompletion. 
(See"Readline," later in thismanual page.) A filenamewhosesuffix matchesoneof 
the entri es in fignore isexcluded from the list of matched filenames. A sam pie value 
is .0:". 

The filmarne for the readiine startup file, overri di ng thedefault of -/.inputrc. (See 
"Readline. ") 

If set, bash reports termi nated background jobsimmediately, ratherthan waiting 
until before printing the next primary prompt. (Seealso the-b option to the set 
built-in command.) 

If set to a value of ignorespace, I inesthat begin with a space character are not entered 
on the history list. If set to a value of ignoredups, lines matching the last history line 
are not entered. A value of ignoreboth combinesthetwo options. If unset, or if setto 
anyother value than the precedi ng, ali lines read by the parser are saved on the 
history list. 

If set, bash attemptsto saveall lines of a multi pie- li ne command in the same history 

entry. This ali ows easy reediting of multi li ne commands 

If set, bash includes filenames beginning with a peri od (.) in the results of pathname 

expansion. 

If set, bash allows pathname patterns which match no fi les (see "Pathname 
Expansion") to expand to a nuli stri ng, ratherthan themselves. 
Thetwo or three characters that control history expansion and tokenization. (See 
"H istory Expansion," later in thismanual page.) The first character isthe history 
expansion character; that is, the character that signals the start of a history expansion, 
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nolinks 



hostname_completion_f ile HOSTFILE 



noclobber 



auto resumé 



no exit on failed exec 



cdable vars 



normally !. Thesecond character isthequick substitution character, which isused as 
shorthand for rerunning the previ ouscommand entered, substituting onestringfor 
another in the command. The default is-. Theoptional third character isthe 
character that si gnifies that the remai nder of the line is a comment, when found as 
the first character of a word, normally #. The history comment character causes 
history substitution to beskipped for the remai ni ngwordson the line. It doesnot 
necessari ly cause the shell parser to treat the rest of the line as a comment. 
If set, the shell doesnot follow symbolic links when executing commands that 
changethecurrent working directory. It usesthephysical directory structureinstead. 
By default, basb follows the logicai chain of directorieswhen performing commands 
that changethecurrent directory, such ascd. Seealso the descri ption of the-p 
option to theset builtin ("Shell Built-in Commands"). 
Containsthenameof a file in the same format as /etc/hosts that should beread 
when theshell needsto complete a hostname. Thefilemay bechanged interactively; 
thenexttimehostnamecompletion isattempted bash addsthecontentsof thenew 
fi le to the al ready existing database. 

If set, bash does not overwritean existing file with the>, >&, and <> redirection 
operators. Thisvariablemay beoverridden when creati ng output fi lesby usi ng the 
redirection operator > instead of >. (Seealso the-c option to theset built-in 
command.) 

T hisvariable controis how theshell interactswith the user and job control. If this 
variable is set, singleword simplecommandswithout redi recti ons are treated as 
candidatesfor resum ption of an existing stopped job. Thereis no ambiguity allowed; 
if thereismorethan onejob beginningwith the stri ngtyped, thejob most recently 
accessed isselected. T he nameof a stopped job, in thiscontext, isthecommand line 
used to start it. If setto thevalueexact, the stri ngsupplied must match the nameof 
a stopped job exactly; if setto substring, the stri ng supplì ed needsto match a 
substri ng of the nameof a stopped job. The substring value providesfunctionality 
analogousto the%? job ID . (See "Job Control," later in thismanual page.) If setto 
any other value, thesupplied stri ng must bea prefixof a stopped job'sname; this 
providesfunctionality analogousto the% job id. 

If this variable exists, a non interacti ve shell will not exit if it cannot executethefile 
specified in the exec built-in command. A n interacti ve shell does not exit if exec 
fails. 

If this is set, an argumentto the ed built-in command that is not a directory is 
assumed to be the nameof avariablewhosevalueisthedirectory to changeto. 



EXPANSION 

Expansion isperformed on the command line after it hasbeen split into words. T nere are seven kindsof expansion 
performed: brace expansion, tilde expansion, parameter and variable expansion, command substitution, arithmetic expan- 
sion, word splitting, and pathnam e expansion. 

Theorder of expansionsisas follows: brace expansion, tilde expansion, parameter, variable, command, and arithmetic 
substitution (donein a left-to-rightfashion), word splitting, and pathnameexpansion. 

On systems that can support it, thereis an additional expansion available: process substitution. 

Only brace expansion, word splitting, and pathnameexpansion can changethenumber of words of the expansion; other 
expansionsexpand a singleword to a single word. The single exception to this isthe expansion of "$§", asexplained earlier. 
(See "Parameters.") 




BRACE EXPAN SION 

Braceexpansion isa mechanism by which arbitrary strings may be generateci. T hi s mechanism issimilar to pathname 
expansion, but the fi lenames generateci need not exist. Patternsto be brace expandeci taketheform of an optional preamble, 
followed by aseriesof comma-separated strings between apairof braces, followed byan optional postamble. The preamble is 
prepended to each stri ng contai ned within the braces, and the postamble isthen appended to each resulti ng stri n g, 
expanding leftto right. 

B race expansions may benested. The resultsof each expanded stri ng are not sorted; leftto right order ispreserved. For 

example, a{d,c,b}e expandsintO ade ace abe. 

Braceexpansion isperformed beforeany other expansions, and any characters special to other expansions are preserved in the 
result. It isstrictly textual. basti doesnotapply any syntactic interp retati on to the contextof the expansion orthetext 
between the braces. 

A correctly formed braceexpansion mustcontain unquoted openingand closing braces, and at least oneunquoted comma. 
Any incorrectly formed braceexpansion isleft unchanged. 

Thisconstruct istypically used asshorthand when the common prefix of the stri ngs to begenerated is longer than in the 
preceding example, such as 

mkdir / usr/ locai /src/bash/ {old, new,dist,bugs} 

or 

chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} 

Braceexpansion i ntroduces a slight incompati bi lity with traditional versionsof su, the Bourne shell. sh does not treat 
opening or closing braces specially when they appear aspart of a word, and preservesthem in the output, bash removes 
braces from wordsasaconsequenceof braceexpansion. For example, a word entered to sh asme{i,2} appears i denti cai ly in 
the output. The same word is output asmei me2 after expansion by basti. If strict compati bili ty with sh isdesired, start 
bash with the-nobraceexpansion flag (see"0 ptions," earlier in thismanual page) or di sable brace expansion with the+o 
braceexpand option to the set command. (See "Shell Built-in Commands.") 

TILDE EXPANSION 

If aword beginswith a tilde character ("), ali of the characters precedingthefirst si ash (orali characters, if thereisno slash) 
aretreated asa possi ble I ogi n name. If thislogin nameisthenull string, thetildeisreplaced with thevalueof theparameter 
home. If home isunset, the home directory of theuser executing the shell issubstituted instead. 

Ifa+ follows the tilde, thevalueof pwd replaces the tilde and + If a- follows, thevalueof oldpwd issubstituted. Ifthevalue 
following thetilde isa valid login name, thetildeand login name are replaced with the home directory associ ated with that 
name. If thenameis invalid, or the tilde expansion fails, theword isunchanged. 

Each variable assignment is checked for unquoted instances of tildes following a : or =. In thesecases, tilde substitution is 
also performed. Consequently, one may use pathnames with tildesin assignmentsto path, mailpath, and cdpath, and theshell 
assigns the expanded value. 

PARAMETER EXPANSION 

T he $ character i ntroduces parameter expansion, command substitution, or arithmetic expansion. Theparameter name or 
symbol to be expanded may beenclosed in braces, which are optional but serve to protect the variable to be expanded from 
characters immediately following it which could be interpreted as part of the name. 

${p a r a me t e r } T he value of par a met e r i s substi tuted . The braces are required when parameter isa positional parameter 

with more than onedigit, or when parameter isfollowed by a character that is not to be interpreted aspart 
of itsname. 

In each of the following cases, word issubjectto tilde expansion, parameter expansion, command substitution, and arithmetic 
expansion. bash testsfor a parameter that isunset or nuli; omitting the colon results in a test only for a parameter that is 
unset. 
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${p a r a me t e r i-word > U se default values. I f p a r a me t e r isunset or nuli, theexpansion of word issubstituted. Otherwise, the 

valueof p a r a me t e r ÌS Substituted. 

${p a r a me t e r :=word } Assign default values. I f p a r a me t e r isunset or nuli, theexpansion of word isassigned to parameter. 

Thevalueof parameter isthen substituted. Positional parametersand special parameters may not be 
assigned to in thisway. 

${p a r a me t e r : ?wo r d > D isplay Errar if nuli orunset. If parameter isnull or unset, the expansion of wor d (oramessageto 
that effect if word isnot present) iswritten to the standard errar and theshell, if it is not interacti ve, 
exits. Otherwise, thevalueof parameter issubstituted. 

${parameter :+word > U se Alternate Value. If parameter isnull or unset, nothing issubstituted; otherwise, theexpansion 
ofword issubstituted. 

${#parameter } Thelength in characters of the value of pa r a met er issubstituted. If parameter is* or », the length 

substituted is the length of * expanded within doublé quotes. 
${parameter#word} Theword isexpandedto produce a pattern just as in pathname expansion. If the pattern matches 

${p a r a me t e r ##wo r d > the beginning Of thevalueof paramet er , then theexpansion isthevalueof parameter with the 

shortest matching pattern deleted (the# case) or the longest matching pattern deleted (the ## case). 
${parameter%word} Theword isexpandedto produce a pattern just as in pathname expansion. If the pattern matchesa 

${parameter%%word } trai li ng portion Of thevalueof parameter , then theexpansion isthevalueof par a mete r with the 

shortest matching pattern deleted (the% case) or the longest matching pattern deleted (the%% case). 

CO M MANO SU BSTITUTIO N 

Command substitution allows the output of acommand to replace the command name. 
There aretwo forms: 

$(command ) 

or 

' c o mma n d ' 

performs the expansion byexecuting command and replacing the command substitution with the standard output of the 
command, with any trailing newlines deleted. 

When the old-style backquoteform of substitution isused, backslash retai ns its I iterai meaningexcept when followed by $, ', 
or \. When usi ng the $ (command > form, ali characters between the parentheses makeup the command; none are treated 
speci al ly. 

Command substitutionsmay benested. To nestwhen usingtheold form, escape the in ner backquoteswith backslashes. 
If the substitution appears within doublé quotes, word spi itti ng and pathname expansion are not performed on the results. 

ARITH METIC EXPANSION 

A ri thmetic expansion allows the evaluation of an arithmetic expression and the substitution of the result. There aretwo 
formatsfor arithmetic expansion: 

$[expression] 
$( (expression) ) 

The expression is treated as if it were within doublé quotes, but a doublé quote inside the braces or parentheses isnot treated 
speci al ly. AH tokensin the expression undergo parameter expansion, command substitution, and quote removal. Arithmetic 
substitutions may be nested. 

The evaluation is performed accordi ng to therules listed under "Arithmetic Evaluation," later in thissection. If ex press i on is 
invaiid, basti prints a message indicating failure and no substitution occurs. 

PRO CESS SUBSTITUTION 

Process substitution issupported on systemsthat support named pipes (FI FO s) or the/dev/td method of naming open files. 
It takes the form of <(i i st ) or >(i i st >. The process list isrun with its input or output connected to a FIFO or somefilein / 




dev/fd.Thenameof this fi lei spassai asan argument to thecurrent command astheresult of theexpansion. If the >(i i st ) 
form isused, writing to the fi le wi II provide input for list. If the<(M st ) form isused, thefilepassed asan argument should 
beread to obtain the output of list. 

On systems that su pport it, process substitution isperformed simultaneously with parameter and variableexpansion, 
command substitution, and arithmetic expansion. 

WORD SPUTTING 

Theshell scanstheresultsof parameter expansion, command substitution, and arithmetic expansion that di d not occur 
within doublé quotes for word splitting. 

Theshell treatseach character of ifs asadelimiter, and splits the results of theother expansionsinto wordson these 
characters. If thevalueof ifs isexactly <space><tab><newiine>, the default, then any sequenceof ifs characters serves to 
delimitwords. If ifs hasavalueotherthan the default, then sequences of the whitespace characters space and tab areignored 
atthebeginningand end of the word, aslong as the whitespace character isin thevalueof ifs (an ifs whitespace character). 
Any character in ifs that isnot ifs whitespace, along with any adjacent ifs whitespace characters, delimitsafield. A 
sequenceof ifs whitespace characters isalso treated asa deli m iter. If thevalueof ifs isnull, no word splitting occurs. ifs 
cannot beunset. 

Explicit nuli arguments(" M or ") are retai ned. I mplicit nuli arguments, resulti ngfrom theexpansion of parametersthat have 
no values, are removed. 

N otethat if no expansion occurs, no splitting isperformed. 
PATHNAM E EXPANSION 

After word splitting, unlessthe-f option hasbeen set, bash scanseach word for the characters \ ?, and [. Ifoneof these 
characters appears, then theword is regarded as a pattern and replaced with an alphabetically sorted list of pathnames 
matching the pattern. If no matching pathnames are found, and theshell variableaiiow_nuii_giob_expansion isunset, the 
word isleftunchanged. If the vari ableis set, and no matches are found, theword is removed. When a pattern isused for 
pathname generation, the character ( . ) at the start of a nameor immediately following a slash must be matched explicitly, 
unless theshell variablegiob_dot_fiienames is set. The slash character must al ways be matched explicitly. In other cases, the 
(. ) character isnot treated speci al ly. 

T he special pattern characters have thefollowing meanings: 

M atches any string, including the nuli stri ng. 
? Matches any single character. 

1 . . . ] M atches any one of the enclosed characters. A pai r of characters separated by a mi nus sign denotes a range; 

any character lexi cai ly between thosetwo characters, inclusive is matched. If the first character following 
the [ isa ! ora -, then any character not enclosed is matched. A - or ] may be matched by including it as 
the first or last character in the set. 

QUOTE REMOVAL 

After the preceding expansions, ali unquoted occurrencesof the characters \, ',and 11 are removed. 
REDIRECTION 

Before a command isexecuted, its input and output may beredirected usi ng a special notation interpreted by theshell. 
Redirection may also beused to open and dose files for thecurrent shell execution environment. Thefollowing redirection 
operatorsmay precede or appearanywhere within a si mple command or may follow a command. Redirectionsareprocessed 
in theordertheyappear, from leftto right. 

In thefollowing descri ptions, if the file descriptor number isomitted, and the fi rst character of the redirection operator is<, 
the redirection refersto the standard input (file descri ptor 0). If thefi rst character of the redirection operator is>, the 
redirection refersto the standard output (fi le descri ptor 1). 
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The word thatfollows the redirection operator i n the followi ng descri ptions is subjected to brace expansion, tilde expansion, 
parameter expansion, command substitution, ari thmetic expansion, quote removal, and pathname expansion. If it expandsto 
morethan oneword, bash reportsan errar. 

N ote that the order of redi rections is significant. For example, the command: 

ls > di ri i s t 2>&1 

directs both standard output and standard errorto the fi le di ri i st , whi le the command 

ls 2>&1 > di ri i s t 

directs only the standard output to file di n i st , because the standard errar wasduplicated as standard output beforethe 
standard output was redirected to di ri i st. 

RED IRECTIN G INPUT 

Redirection of input causes the file whosenameresultsfrom the expansion of word to beopened for reading on file 
descriptorn, orthestandard input (fi le descri ptor 0) if n is not specifi ed. 

Thegeneral format for redi recti ng input is 

[n ] <wo r d 

RED IRECTIN G OUTPUT 

Redirection of output causes the fi le whosenameresultsfrom theexpansion of word to beopened forwritingon file 
descriptorn, orthestandard output (fi le descri ptor 1) if n is not specifi ed. If the file does not exist, it iscreated; if it does 
exist it istruncated to zero size. 

Thegeneral format for redi recti ng output is 

[n ]>wor d 

If the redirection operator is>|, then thevalueof the -c option to the set built-in command isnottested, and filecreation is 
attempted. (Seealso the description of nociobber under "Shell Vari ables," earlier in thismanual page) 

APPENDING REDIRECTED OUTPUT 

Redirection of output in thisfashion causes thefilewhosenameresultsfrom theexpansion of word to beopened for 
appendi ng on fi le descri ptor n, orthestandard output (fi le descri ptor 1) if n isnot specified. If the fi le does not exist, it is 
created. 

Thegeneral format for appendi ng output is 

[n ]»wo r d 

RED I RECTI N G STANDARD OUTPUTAND STANDARD ERROR 

bash allows both the standard output (fi le descri ptor 1) and the standard errar output (file descriptor 2) to be redirected to 
thefilewhosenameistheexpansion of word with thisconstruct. 

There aretwo formatsfor redi recti ng standard output and standard errar: 

&>wo r d 

and 

>&wo r d 

Of thetwo forms, thefirst is preferred. This is semanti cally equivalent to 

>word 2>&1 

HERE-DOCUMENTS 

Thistypeof redirection i nstructs the shell to read input from thecurrent sourceuntil a li ne contai ni ng only word (with no 
trai li ng blanks) isseen. AH of thelines read up to that point are then used as the standard input for a command. 




T he format of here-documentsisasfollows: 

«[-]word here - document del imi ter 

N o parameter expansion, command substitution, pathnameexpansion, or arithmetic expansion is performed on word. If any 
characters in word arequoted, the dei i mi ter istheresult of quote removal on word, and the li nes in the he re- document arenot 
expanded. Otherwise, ali linesof thehere- document aresubjected to parameter expansion, command substitution, and 
arithmetic expansion. In the latter case, the pai r \<newiine> isignored, and \ must beused to quote the characters \, $, and '. 

If the redirection operator is«-, then ali leadingtab characters are stri pped from input linesand thelinecontaining 
del imi ter. Thisallowshere-documentswithin shell scriptsto beindented in a naturai fashion. 

DUPLICATING FILE DESCRIPTORS 

The redirection operator: 

[n ]<&word 

isused to duplicate input file descriptors. If word expandsto oneor moredigits, the fi le descri ptor denoted by n ismadeto be 
a copy ofthat fi le descri ptor. If word evaluatesto -, file descri ptor n isclosed. If n isnot specified, the standard input (file 
descri ptor 0) isused. 

The operator: 

[n ]>&wo r d 

isused similarly to duplicate output fi le descriptors. If n isnot specified, the standard output {file descriptor 1) isused. Asa 
special case, if n isomitted, and word does not expand to oneor moredigits, the standard output and standard error are 
redirected as descri bed previ ously. 

0 PEN IN G FILE D ESCRIPTO RS FO R READ ING AND W RITI N G 

The redirection operator: 

[n ]<>word 

causes the fi le whosenameis the expansion of word to beopened for both reading and writing on fi le descri ptor n, or asthe 
standard input and standard output ifn isnot specified. If the file does not exist, itiscreated. 

FUNCTIONS 

A shell function, defined asdescribed above under "Shell Grammar," storesaseriesof commandsforlaterexecution. 
Functionsareexecuted in thecontext of thecurrent shell; no new processi screated to interpretthem (contrastthiswith the 
execution of a shell script). W hen a function isexecuted, theargumentsto the function become the positi onal parameters 
during its execution. The special parameter* isupdated to reflect thechange. Positional parameter 0 isunchanged. 

Variables locai to the function may bedeclared with the locai built-in command. Ordì nari ly, vari ables and their valuesare 
shared between thefunction and its Caller. 

If the built-in command return isexecuted in afunction, thefunction completesand execution resumeswith thenext 
command after thefunction cali. W hen afunction completes, the valuesof the positional parameters and the special 
parameter* arerestored to thevaluesthey had prior to function execution. 

Function namesmay belisted with the-t option to thedeciare or typeset built-in commands. Functionsmay beexported 
so that subshells automatically havethem defined with the-t option to the export builtin. 

Functionsmay berecursive. N 0 limit isimposed on thenumber of recursivecalls. 
ALIASES 

The shell maintainsa list of aliases that may be set and unset with theaiìas and unaiias built-in commands. (See "Shell 
Built-in Commands."). The first word of each command, if unquoted, ischecked to seeif it hasan alias. If so, that word is 
replaced by thetext of the alias. The alias nameand thereplacementtext may contai n any valid shell input, including the 
meta characters listed above, with theexception that the alias name may not contai n =. The first word of thereplacement text 
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is tested for aliases, but a word that is identical to an alias bei ng expanded isnot expanded a second time. This meansthat 
onemay alias is to is -f, for instance, and bash doesnottry to recursively expand thereplacement text. If thelast character 
of the alias value is a blank, then thenext command word followi ng the alias is also checked for alias expansion. 

Aliases are created and listed with the alias command, and removed with theunaiias command. 

There isno mechanism for using arguments in thereplacement text, as in csh. If arguments are needed, a shell function 
should be used. 

Aliases are not expanded when the shell isnot interactive. 

T he rules concerni ng the defi ni tion and useof aliases are somewhat confusi ng. basti always reads at least one complete li ne of 
input beforeexecuting any of the commands on that line. Aliases are expanded when a command isread, not when it is 
executed. Therefore, an alias defi ni tion appearing on thesamelineasanother command doesnot takeeffect until thenext 
lineof input isread. This meansthat the commands followi ng the alias defi nition on that lineare not affected by thenew 
alias. This behavior is also an issuewhen functions are executed. Aliases are expanded when the function defi nition isread, 
not when the function is executed, because a function defi nition isitself a compound command. Asaconsequence, aliases 
defi ned in a function are not available until after that function is executed. To besafe, always put alias defi nitionson a 
separate line, and do not usealiasin compound commands. 

Notethatforalmost every purpose, aliases are superseded by shell functions. 
JOB CONTROL 

Job control refersto the abi I ity to selectively stop (suspend) theexecution of processes and continue (resumé) their execution 
ata later point. A user typi cally employs this faci li ty via an i nteracti ve i nterface su ppl i ed jointly by the system's terminal 
driver and bash. 

The shell associ atesa job with each pipeline. It keepsatableof currently executingjobs, which may be listed with thejobs 
command. W hen bash startsa job asynchronously (in the background), it printsa li ne that looks li ke this: 

[1] 25647 

indicati ng that this job isjob number 1 and that the process ID of thelast processin the pipeline associ ated with this job is 
25647. AH of the processes in a single pipeline are members of thesamejob. bash usesthejob abstraction asthe basisfor job 
control. 

To faci li tate the impl ementati on of the user i nterface to job control, the system maintainsthenotion of a current terminal 
process group ID . M embersof this process group (processes whose process group ID isequal to the current terminal process 
group ID ) receivekeyboard-generated signals such assiGiNT. These processes are said to bein theforeground. Background 
processes are those whose process group ID differsfrom the termi nal's; such processes are immune to keyboard-generated 
signals. 0 nly foreground processes are al lowed to read from or writeto the terminal. Background processes that attempt to 
read from (writeto) the terminal aresent asiGrriN (sigttou) signal by the terminal driver, which, unlesscaught, suspends 
the process. 

If the operati ng system on which bash isrunningsupportsjob control, bash allowsyou to useit. Typing the suspend 
character (typi cally "z, control -z) whi le a process is running causesthat process to bestopped and returnsyou to bash. 
Typing the delayed suspend character (typically "y, control -y) causes the process to bestopped when it attemptsto read 
input from the terminal, and control to bereturned to bash. You may then mani pulate the state of this job, using the bg 
command to continue it in the background, thetg command to conti nueit in theforeground, or the km command to kill 
it. A Ctrl+Z takeseffect immediate! y, and hastheadditional sideeffect of causi ng pendi ng output andtypeahead to be 
discarded. 

T here are a number ofwaysto referto a job in the shell. T he character % introducesajob name. Job number n may be 
referred to as%n. A job may also bereferred to using a prefixof the name used to start it, or usi ng a substri ng that appears in 
its command line. For example, %ce refersto a stopped ce job. If a prefix matchesmorethan one job, bash reportsan error. 
Using%?ce, on theother hand, refersto any job contai ni ng the stri ng ce in its command line. If the substri ng matchesmore 
than one job, bash reportsan error. The symbols%% and %+ referto the shell 's notion of the current job, which is thelast job 




stopped whileit wasin the foreground. The previ ous job may bereferenced usi ng %-.l n output pertainingto jobs (for 
example, theoutput of thejobs command), thecurrent job isalwaysflagged with a+, and thepreviousjobwith a-. 

Simply namingajob can beused to bring it into the foreground: %i isasynonym for fg %1, bringingjob 1 from the 
background into the foreground. Similarly, %i & resumesjob 1 in the background, equivalent to bg %1. 

Theshell learnsimmediately whenever a job changes state. N ormally, bash waitsuntil it isabout to print a prompt before 
reporti ng changes in ajob's status so asto not interrupt any other output. If the -b option to the set built-in command is set, 
bash reportssuch changes immediately. (Seealso the descri ption of thenotity variablein "Shell Variables," earlier in this 
manual page.) 

If you atterri ptto exit bash whilejobs are stopped, theshell printsa messagewarningyou. You may then use the jobs 
command to inspect their status. If you do this, ortry to exit again immediately, you arenotwarned again, and the stopped 
jobs are termi nated. 

SIGNALS 

When bash isinteractive, it ignores sigterm (so that mi a doesnot kill an interacti ve shell), and sigint iscaught and 
handled (so thatthewait built-in isinterruptible). In ali cases, bash ignores sigquit. If job control isin effect, bash ignores 

SIGTTIN, SIGTTOU, and SIGTSTP. 

Synchronousjobsstarted bybash have signals set to thevalues inherited by theshell from itsparent. When job control isnot 
in effect, background jobs (jobs started with &) ignore sigint and sigquit. Commandsrun asa result of command substitu- 
tion ignore the keyboard-generated job control signals sigttin, sigttou, and sigtstp. 

COMMAND EXECUTION 

After a command hasbeen split into words, if it resultsin a si mple command and an optional list of arguments, the 
f o 1 1 ovvi n g acti on s are taken . 

If the command name contai ns no slashes, theshell attemptsto locate it. If there exi stsa shell function by that name, that 
function isinvoked as descri bed earlier in "Functions." If the name doesnot match a function, theshell searchesfor it in the 
list of shell bui Iti ns. If a match isfound, that bui Iti n isinvoked. 

If the name is nei ther a shell function nor a bui Iti n, and contai ns no slashes, bash searcheseach element of thePATH for a 
directory contai ni ngan executablefileby that name. If thesearch isunsuccessful, theshell printsan errar messageand 
returns a nonzero exit status. 

If thesearch issuccessful, or if the command namecontainsoneor more slashes, theshell executesthenamed program. 
Argument 0 is set to the name given, and the remaini ng arguments to the command are set to the arguments gi ven, if any. 

If this execution fails because the file is not in executabl e format, and thefile isnot a directory, it isassumed to bea shell 
script, afilecontaining shell commands. A subshell isspawned to execute it. This subshel I reinitializes itself, so that the effect 
isas if a new shell had been invoked to handle the script, with theexception that the locationsof commands rem embered by 
theparent (seehash under "Shell Built-in Commands") are retai ned by the chi Id. 

If the program isafilebeginningwith #!, the remainder of the first line specifiesan interpreter for the program. Theshell 
executesthespecified interpreter on operati ng systemsthat do not handle this executable format themselves. The arguments 
to the interpreter consist of a single optional argument following the interpreter nameon the first line of the program, 
followed by the name of the program, followed by the command arguments, if any. 

ENVIRONMENT 

When a program isinvoked, it is given an array of stri ngs cali ed theenvironment. Thisisa list of name/valuepairs, of the 

form name=value. 

Theshell allowsyou to manipulate theenvironment in several ways. 0 n invocation, theshell scansitsown environment and 
createsa parameter for each namefound, automatically marking itfor export to child processes. Executed commands inherit 
theenvironment. The export and declare-x commands al low parameters and functions to beadded to and ddeted from the 
environment. If the valueof a parameter in theenvironment ismodified, the new value becomes part of theenvironment, 



Parti: U ser Commands 



replaci ng the old. Theenvironment inherited by any executed command consistsof the shell 's i n iti al environment, whose 
valuesmay bemodified in the shell, lessany pairsremoved by theunset command, plus any additions via the export and 
declare -x commands. 

Theenvironment for any simple command orfunction may beaugmented temporarily by prefixing itwith parameter 
assignments, asdescribed earlier in "Parameters." Theseassignment statementsaffect only theenvironment seen by that 
command. 

If the-k flag isset (seetheset built-in command), then ali parameter assignments are pi aced in the environment for a 
command, not just those that precede thecommand name. 

When bash invokesan external command, thevariable isset to the full path name of thecommand and passed to that 
command in its environment. 

EXIT STATUS 

Forthepurposesof the shell, a command which exitswith a zero exit status hassucceeded. An exit status of zero indicates 
success. A non-zero exit status indicates fai Iure. When a command termi nateson a fatai signal, basti usesthevalueof 
128+signai as the exit status. 

If a command isnot found, the chi Id process created to executeit returns a status of 127. If a command isfound but isnot 
executable, the return status is 126. 

bash itself returns the exit status of the last command executed, unlessasyntaxerror occurs, in which caseit exitswith a non- 
zero value. (Seealso theexit built-in command.) 

PROMPTING 

When executing interactively, bash displaystheprimary prompt psi when it is ready to read a command, and thesecondary 
prompt ps2 when it needs more input to complete a command. bash allowsthese prompt stri ngsto becustomized by 
inserting a number of backslash-escaped special characters that are decoded asfollows: 



\t 


Thecurrenttimein hh: hh: ss format 


\d 


The date in "Weekday M onth Date" format (forexample, "TueM ay 26") 


\n 


N ewline 


\s 


T he name of the shell, thebasenameof $0 (the porti on following the final slash) 


\w 


T he current working directory 


\W 


The basename of the current worki ng di rectory 


\u 


The username of the current user 


\h 


Thehostname 


\# 


Thecommand number of thiscommand 


\! 


The history number of thiscommand 


\$ 


If the effective U I D is 0, a #, otherwisea$ 


\nnn 


The character correspondi ng to the octal number nnn 


\\ 


A backslash 


u 


Begin asequenceof nonprintingcharacters, which could beused to embed aterminai control sequence 




into the prompt 


\] 


End a sequence of nonprinting characters 



Thecommand number and the history number are usuai ly differenti the history number of a command isits position in the 
history list, which may include commands restored from the history fi le (see "H i story," later in thismanual page), whilethe 
command number isthe position in the sequence of commands executed during the current shell session. After the stri ng is 
decoded, it isexpanded via parameter expansion, command substitution, arithmetic expansion, and word splitting. 



bash 




READ UN E 



This isthe library that handles reading input when usingan interactiveshell, unlessthe-noiineediting option isgiven. By 
default, the line editing commands are similar to thoseof emacs. A vi-style li ne editing interface is also available. 

In this section, theemacs-style notation isused to denote keystrokes. Control keysaredenoted by c-key ; for example, c-n 
meansCtrl-N . Similarly, meta keysaredenoted byni-key, som-x meansuieta-x. (On keyboardswithout a meta key, m-x 
means Esc-X; that is, press the E scape key, then theX key. Thismakes ESC the meta prefix. Thecombination m-c-x means 
Esc-Control-x, or press the E scape key then hold the Control key whi le pressing the X key.) 

The default key-bindingsmay bechanged with a / .inputrc file The valueof the shell variable inputrc, if set, isused instead 
of "/.inputrc. Other programsthat use this library may add their own commands and bindings. 

For example, placing 

M-Control-u: uni versai - argument 

or 

C-Meta-u: uni versai - argument 

into the /.inputrc would makein-c-u executethereadiine command universal-argument.Thefollowing symbolic character 
namesarerecognized: rubout, del, esc, lfd, newline, ret, return, spc, space, and tab. In addition to command names, 
readiine allows keysto be bound to a stri ng that is inserted when the key ispressed (amacro). 

Readline is customized by putti ng commands in an initialization file T he nameof this file istaken from the valueof the 
inputrc variable. If that variable is unset, the default is"/. inputrc. When a program that uses the readiine library startsup, 
theinit fileisread, and the key bindings and vari ables are set. T nere are only a few basic constructsallowed in the readiine 
init file Blank linesareignored. Lines beginning with a# arecomments. Lines beginning with a$ indicate conditional 
constructs. Other lines denote key bindings and variable setti ngs. 

T he syntax for controll ing key bindings in the "/.inputrc fileissimple. AH that isrequired isthe nameof the command or 
thetext of a macro and a key sequenceto which it should be bound. The name may bespecified in oneof two ways: asa 
symbolic key name, possi bly with M età- or Control- prefixes, or asa key sequence. W hen usingtheform key name: fu net i ori- 
narne or macro, key name is the name of a key spelled out in English. For example, 

Control-u: uni versai -argument 
Meta-Rubout: backward-kill-word 
Control-o: ">&output" 

In the precedi ng example, c-u is bound to thefunction universai-argument, m-del is bound to thefunction backward-km- 
word.and c-o isbound to run the macro expressed on therighthand side (that is, to insert thetext >&output into the line). 

In thesecond form, -keyseq': fune ti on- name or macro, keys eq differsfrom key name in that stri ngs denoti ng an enti re key 
sequence may bespecified by placing the sequence within doublé quotes. SomeGN U emacs-style key escapescan beused, as 
in thefollowing example: 

" \C-u" : uni versai - argument 
"\C-x\C-r": re-read-init-f ile 
" \e[ 1 1 ' " : "Function Key 1 " 

In thisexample, C-u isagain bound tO thefunction universal-argument. C-x C-r isbound tO thefunction re-read-init-fUe, 

and esc[h" isbound to insert thetext Function Key 1 . T hefull set of escape sequences is 

\c- Control prefix 

\m- Meta prefix 

\e A n escape character 



V 



w 



Backslash 
L iterai " 
L iterai ' 
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When entering thetext of a macro, si ngle or doublé quote should beused to indicate a macro definiti on. U nquoted text is 
assumedto beafunction name. Backslash will quote anycharacter in the macro text, including " and '. 

bash allowsthecurrent readiine key bindingsto bedisplayed or modified with thebind built-in command. The editing 
modemay beswitched during interactiveuseby usingthe-o option to the set built-in command. (See "Shell Built-in 
Commands.") 

Readiine has vari ablesthat can beused to further customizeits behavior. A variablemay be set in the input re fi le with a 
statement of theform: 

set variable-name value 

Except wherenoted, readiine vari ables can takethevalueson or off. Thevariablesand their default valuesareasfollows: 



horizontal-scroll-mode (Off) 

editing-mode (emacs) 
mark-modif ied-lines (off ) 
bell-style (audible) 



comment-begin ("# 
meta-flag (Off) 

convert-meta (on) 



output-meta (off) 
completion-query-items ( 1 00) 

keymap (emacs) 

show-all-if-ambiguous (Off ) 
expand-tilde (Off ) 



When setto on, makes readiine use a si ngle line for display, scrolli ng the input 
horizontally on asinglescreen li ne when it becomeslonger than thescreen width 
ratherthan wrappingto a new line. 

Controls whether readiine beginswith a set of key bindingssimilarto emacs or vi. 

editing-mode Can be Set tO either emacs or vi. 

If set to on, hi story linesthat havebeen modified aredisplayed with a precedi ng 
asterisk (*). 

Controls what happenswhen readiine wantsto ring the terminal beli. If set to none, 
readiine never rings the beli. If set to visibie, readiine usesa visi ble bel I if oneis 
available. If setto audibie, readiine attemptsto ring the termi nal's beli. 
The stri ngthat isinserted in vi mode when thevi-comment command isexecuted. 
If set to on, readiine will enable eight-bit input (that is, it will not strip the high bit 
from thecharactersit reads), regardlessof what the terminal claimsit can support. 
If setto on, readiine will convert characters with theeighth bit setto an ASCII key 
sequenceby stri pping theeighth bit and prependi ng an escape character (in effect, 
usi ng escape as the meta prefix). 

If setto on, readiine will display characters with theeighth bit set directly rather 
than as a meta-prefixed escape sequence 

This determi nes when the user isqueried about viewing thenumber of possi ble 
completions generated by the possibie-compietions command. It may be set to any 
integer value greater than or equal to zero. If thenumber of possible completions is 
greater than or equal to the value of this vari able, the user isasked whether or not he 
wishesto view them; otherwise, they are simply listed on the terminal. 
Set thecurrent readiine keymap. The set of legai keymap namesis emacs, emacs- 

standard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. vi ÌS 

equivalent to vi-command; emacs isequivalent to emacs -standard. The default value is 
emacs; the value of editing-mode al so affeets the default keymap. 
Thisalters the default behavior of the completion functions. If set to on, words 
which havemorethan onepossiblecompletion cause the matchesto belisted 
immediately instead of ringing the beli. 

If set to on, tilde expansion isperformed when readiine attemptsword completion. 



Readiine impletnentsa facility similar in spi ritto the condì ti onal compilation featuresof theC preprocessor that al lows key 
bindingsand vari able setti ngsto beperformed astheresult of tests. Therearethree parser di recti vesused. 

$if The$if construct allows bindingsto bemadebased on the editing mode, the 

terminal beingused, or theapplication usi ng readiine. Thetext of the test extends 
to the end of the line; no characters are required to isolate it. 




mode The mode= forni of the$if directiveisused to test whether 

readiine isin emacs or vi mode Thismay beused in conjunction 
with the set keymap command, for instance, to set bindingsin the 

emacs -standard and emacs-ctlx keymapsonly if readiine ÌS Starti ng 

out in emacs mode. 

terni Theterm= form may beused to include terminal-specific key 

bindings, perhapsto bind the key sequences output bythe 
terminali function keys. The word on theright sideof the= is 
tested against the full nameof the terminal and theportion of the 
terminal namebeforethefirst-. Thisallowssun to match both 
sun and sun-cmd, for instance. 

application T he application COnstruCt ÌSUSed tO include application-specific 

settings. Each program usi ng the readiine library sets the 
application name, and an initialization filecan test for a parti cui ar 
value. Thiscould beused to bind key sequences to functions 
useful for aspecific program. For instance, thefollowing 
command adds a key sequence that quotes the current or previ ous 
word in basti: 

$if Basti 

# Quote the current or pr evi ous wor d 

"\C-xq": "\eb\"\ef\"" 

$endif 

$endif This command, asshown in the precedi ng example, termi natesan $if command. 

$eise Commandsin thisbranch ofthe$if directiveareexecuted if the test fai Is 

readiine commandsmay begiven numeric arguments, which normally act asa repeat count. Sometimes, however, it isthe 
sign of the argument that issignificant. Passinganegativeargument to a command that actsin theforward direction (such as 
km-line) causesthat command to act in a backward direction. Commandswhosebehavior with arguments deviatesfrom 
this are noted. 

When a command isdescribed as killingtext, thetext deleted issaved for possi ble future retri eval (yanking). The killed text 
issaved in a kill-ring. Consecutive kills cause the text to beaccumulated into oneunit, which can beyanked ali at once. 
Commandsthat do not kill text separate the chunks of text on the kill-ring. 

Thefollowing isa listof thenamesof thecommandsand the default key sequences to which they are bound. 
Commandsfor M oving 



beginning-of-line (C-a) 
end-of-line (C-e) 
forward-char (C-f ) 
backward-char (c-b) 
forward-word (M-f ) 

backward-word (lK-b) 

clear-screen (c-l) 

redraw-current-line 



M oveto the start of the current line. 
M oveto the end of the line. 
M oveforward a character. 
M ove back a character. 

M oveforward to the end of the next word. Wordsarecomposed of alphanu- 
meric characters (lettere and digits). 

M ove back to the start of this, or the previous, word. W ords are composed of 

alphanumeric characters (letters and digits). 

Clearthescreen leaving the current li ne at the top of thescreen. With an 

argument, refresh the current linewithout clearing thescreen. 

Refresh thecurrent line By default, thisisunbound. 



] 
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Commandsfor M anipulating the H istory 



accept-line (Newline, Return) 

previous-history (c-p) 
next-history (C-n) 
beginning-of-history (M-<) 
end-of-hìstory (M->) 
reverse-search-history (C-r) 

forward-search-history (c-s) 

non-incremental-reverse- 
search-history (M-p) 
non-incremental-f orward- 
search-history (M-n) 
history-search-f orward 

history-search-backward 

yank-nth-arg (lU-C-y) 



yank-last-arg (M-., M-_) 
shell-expand-line (M-C-e) 

history-expand-line (M-") 
insert-last-argument (M-., M-_ 
operate-and-get-next (C-o) 

Commandsfor ChangingText 



Accept the line regardlessof wherethecursor is. If this line is non-empty, add it 
to the hi story list accordi ngto the state of the hist-control variable. If the line is 
a modified history line, then restare the history lineto its originai state. 
Fetch thepreviouscommand from the history list, moving back in the list. 
Fetch thenextcommand from the history list, moving forward in the list. 
M oveto the first line in the history. 

M oveto the end of the input history, that is, the line currently beingentered. 

Search backward starting at thecurrent line and moving "up" through the 

history as necessary. This isan incrementai search. 

Search forward starting at thecurrent line and moving "down" through the 

history as necessary. This isan incrementai search. 

Search backward through the history, starti ngat thecurrent line usi ng a non- 

incremental search fora stri ngsupplied by the user. 

Search forward through the history usinga nonincremental search fora stri ng 

supplied by the user. 

Search forward through the hi story for the stri ng of characters between the start 
of thecurrent line and thecurrent point. Thisisa nonincremental search. By 
default, thiscommand isunbound. 

Search backward through the hi story for the stri ngof characters between the start 
of thecurrent line and thecurrent point. Thisisa nonincremental search. By 
default, thiscommand isunbound. 

Insert the first argument to thepreviouscommand (usually thesecond word on 
theprevious line) at point (thecurrent cursor positi on). W ith an argument n, 
insert the nth word from thepreviouscommand (thewordsin theprevious 
command begin with word a). A negative argument inserts the nth word from 
the end of thepreviouscommand. 

Insert thelast argument to theprevious command (thelast word on theprevious 
line). W ith an argument, behaveexactly like @codefyank-nth-argg. 
Expand the line the way the shell doeswhen it readsit. This performs alias and 
history expansion aswell asall of theshell word expansions. See"H istory 
Expansion," later in this manual page, for a descri ption of history expansion. 
Perform history expansion on thecurrent line. See"H istory Expansion." 

A Synonym foryank-last-arg. 

Accept thecurrent li ne for execution and fetch thenext li ne relati veto the 
currentlinefrom the history for editing. Any argument isignored. 



delete-char (c-d) 



backward-delete-char (Rubout) 

quoted-insert (C-q, C-v) 

tab-insert (C-v Tab) 
self-insert (a, b, A, 1 , !, . . . ) 



D elete the character under the cursor. If poi nt is at the beginning of the line, 
there are no characters in the line, and the last character typed was not c-d, then 
return eof. 

Delete the character behind the cursor. W hen given a numeric argument, save 
thedeleted text on the kill-ring. 

Add thenext character that you typeto the lineverbatim. This is how to insert 
characters like c-q, for example. 
Insert a tab character. 
Insert the character typed. 
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transpose-chars (C-t) 

transpose-words (M-t) 
upcase-word (lK-u) 
downcase-word (lK-l) 
capitalize-word (M-c) 

Killing and Yanking 



D rag the character before point forward over thecharacter at point. Point moves 
forward aswell. If point isattheend of the line then transpose the two 
characters before poi nt. N egative arguments don't work. 
Drag the word behind the cursor past the word in front of the cursor, moving 
the cursor over that word aswell. 

U ppercasethecurrent (or following) word. W ith a negative argument, do the 
previ ous word, but do not move point. 

Lowercasethecurrent (orfollowing) word. W ith a negative argument, do the 
previ ous word, but do not move point. 

Capitalizethecurrent (or following) word. W ith a negative argument, do the 
previ ous word, but do not move point. 



kill-line (C-k) 

backward-kill-line (C-x C-Rubout) 
UNIX-line-discard (C-u) 
kill-whole-line 

kill-word (M -d) 

backward-kill-word (lK-Rubout) 

UNIX-word-rubout (C-w) 

delete-horizontal-space 
yank (c-y) 
yank-pop (M-y) 

N umeric Arguments 



Kill thetext from thecurrent cursor posi tion to the end of the line. 

Kill backward to the beginning of the line 

Kill backward from pointto the beginning of the line. 

Kill ali characters on thecurrent line, no matterwhere the cursor is. By default, 

thisisunbound. 

Kill from thecursorto theend of thecurrent word, or if between words, to the 
end of the next word. Word boundariesarethesameasthoseused bytorward- 

word. 

Kill the word behind the cursor. Word boundariesarethesameasthoseused by 

backward-word. 

Kill theword behind thecursor, usingwhitespaceasaword boundary. Theword 
boundaries are different from backward-km-word. 
Delete ali spacesand tabsaround point. By default, thisisunbound. 
Yank the top of the kill ring into the buffer at the cursor. 
Rotate the kill- ring, and yank thenew top. Only works following yank or yank- 
pop- 



digit-argument (M-0, M-1, 
universal-argument 

Completi ng 



Add this digit to the argument al ready accumulati ng, or start a new argument. 
m- startsa negative argument. 

Each timethisisexecuted, theargument count ismultiplied by four. The 
argument count is initially one so executing thisfunction thefirst timemakes 
theargument count four. By default, this isnot bound to akey. 



complete (TAB) 



possible-completions (M-?) 
insert-completions 

complete-filename (M-/) 



Attempt to perform completion on thetext before point. Bash attempts 

completion treati ng the text as a variable (if the text begins with $), username (if 

thetext beginswith '), hostname(if thetext beginswith e), or command 

(includi ng aliasesand functions) in turn. If noneof theseproducesa match, 

filenamecompletion isattempted. 

List the possible completions of the text before point. 

Insert ali completionsof thetext before point that would havebeen generated by 

possibie-compietions. By default, this isnot bound to a key. 

Attempt filenamecompletion on thetext before point. 



continues 
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Completi ng 



possible-f ilename-completions (c-x /) 
complete-username (M-") 
possible-username-completions (C-x ') 
complete-variable (m-$) 
possible-variable-completions (c-x $) 

complete-bostname (M-@) 
possible-hostname-completions (c-x @) 
complete-command (M-l) 

possible-command-completions (c-x !) 
dynamic-complete-bistory (M-TAB) 
complete-into-braces (M-{) 



Keyboard M acros 



List the possi ble completions of thetext beforepoint, treating it asafilename. 
Atterri pt completion on thetext beforepoint, treating itasa username 
List the possible completions of thetext before point, treating it as a username. 
Atterri pt completion on thetext beforepoint, treating it asashell variable 
List the possi ble completions of thetext beforepoint, treating it asashell 
variable. 

Atterri pt completion on thetext beforepoint, treating it asa hostname. 

List the possi ble completions of thetext beforepoint, treating it asa hostname. 

Atterri pt completion on thetext beforepoint, treating it asacommand name. 

Command completion attemptsto match thetext against aliases, reserved words, 

shell functions, builtins, and finally executablefilenames, in thatorder. 

List the possi ble completions of thetext beforepoint, treating it asacommand 

name 

Atterri pt completion on thetext beforepoint, compari ng thetext against lines 
from the history list for possi ble completion matches. 
Perform filename completion and return the list of possible completions enclosed 
within braces so the list isavailableto the shell. (See "Brace Expansion," earlier in 
thismanual page.) 



start-kbd-macro (C-x () 
end-kbd-macro (C-x )) 

call-last-kbd-macro (C-x e) 
M iscellaneous 



Begin savi ng the characters typed into thecurrent keyboard macro. 

Stop savi ng the characters typed into thecurrent keyboard macro and savethe 

definition. 

Re-executethelast keyboard macro defined, by making the characters in the 
macro appear asif typed at the keyboard. 



re-read-init-f ile (C-x C-r) 
abort (c-g) 

do-uppercase-version (M-a, M-b, . 
pref ix-meta (ESC) 
undo (C-_, C-x C-u) 
revert-line (lK-r) 

tilde-expand (M-") 
dump-functions 

display-sbell-version (c-x C-v) 
emacs-editing-mode (C-e) 



Read in thecontentsof your initfile, and incorporate any bindings or variable 
assignmentsfound there. 

Abort the current editing command and ring the terminal's beli (subject to the 
setti ngof bell-style). 

Run thecommand that is bound to thecorresponding uppercasecharacter. 

Metafy the next character typed. ESC-f isequivalentto Meta-f. 

Incrementai undo, separately remembered foreach line. 

U ndo ali changesmadeto thisline. Thisisliketyping the undo command 

enough timesto return thelineto itsinitial state. 

Perform tilde expansion on thecurrent word. 

Printall of the functions and their key bindings to thereadiine output stream. If 
a numeric argument issupplied, the output isformatted in such away that it can 
bemadepartof an inputrcfile. 

D i splay version information about thecurrent instanceof basti. 
When in vi editing mode, thiscausesaswitch to emacs editing mode. 



HISTORY 



When interactive, the shell provi des access to thecommand history, thelistof commands previously typed. Thetext of the 
last histsize commands (default 500) issaved in a history list. The shell storeseach command in the history list prior to 
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parameter and variableexpansion (see "Expansion," earlier in thismanual page) but after history expansion is performed, 
subjectto thevaluesof theshell variablescommand_oriented_history and histcontrol. On startup, the history isinitialized 
from thefilenamed by the variable histfile (default "/.bashjiistory). H ISTFILE istruncated, if necessary, to contain no 
morethan histfilesize lines. Thebuilt-in command fc (see Shell Built-in Commands, later in thismanual page) may be 
used to list or edit and re-executea portion of the history list. The history bui Iti n can beused to display the history list and 
mani pulate the history file. W hen usi ng the command-li ne editing, search commands are available in each editing modethat 
provide access to the history list. W hen an interactive shell exits, thelast histsize lines are copied from the history list to 
histfile. If histfile isunset, or if the history file is unwritable, the history is not saved. 

HISTORY EXPANSION 

Theshell supports a history expansion featurethat issimilar to the history expansion in csh. Thissection describeswhat 
syntaxfeatures are available. Thisfeatureisenabled by default for interactiveshells, and can bedisabled using the h option to 
the set built-in command. (See "Shell Built-in Commands," later in thismanual page.) N oninteractive shells do not perform 
history expansion. 

H i story expansion isperformed immediately after a complete line isread, before the shell breaksitinto words. Ittakes place 
in two parts. The first isto determinewhich line from the previous history to use duri ng substitution. Thesecond isto select 
porti ons of that li ne for i nclusion i nto the current one. T he I i ne selected from the previous hi story is the event, and the 
porti onsof that li ne that areacted upon are words. The line is broken into words in the same fashion aswhen reading input, 
so that several meta character-separated words surrounded by quotes are considered as oneword. 0 nly the backslash (\) and 
singlequotescan quote the history escapecharacter, which is ! by default. 

Theshell allows control of thevariouscharactersused by the history expansion mechanism. (Seethedescription of histchars 
under "Shell Vari ables, " earlier in thismanual page.) 

EVENT DESIGNATORS 

An event desi gnatoris a referenceto a command line entry in the history list. 

Start a history substitution, except when followed by a blank, newline, =, or (. 
Referto the previous command. Thisisasynonym for 1-1. 
Referto command li ne n . 
Referto the current command line minusn . 
!st ri ng Referto themost recent command starti ng with st ri ng. 

i?str i ng [?] Referto themost recent command contai ni ng stri ng. 

"stri ngi"stn n g 2 " Q uick substitution. Repeat the last command, replaci ng s t r i ngi with stri ng2. Equivalentto i!:s/ 

stri ngi/stri n g 2 / . (See"M odifiers," laterin thismanual page.) 
!# The enti re command line typed so far. 

WORD DESIGNATORS 

A colon (:) separates the event specificati on from the word designator. It can beomitted if the word designator beginswith a 
-, $, \ or%. Words are numbered from thebeginning of the line, with the first word being denoted by a a (zero). 

a (zero) Thezeroth word. For the shell, thisisthe command word, 

n Thenthword. 

Thefirst argument. That is, word 1. 
$ The last argument. 

% The word matched by themost recent ?string? search. 

x-y A rangeof words; -y abbrevi atese-y. 

Ali of the words but thezeroth. T hi sis a synonym for 1-$. It isnot an errorto use* if there isjust 

oneword in the event; theempty stri ng isreturned in that case, 
x* Abbreviates x-$. 

x- Abbreviates x-$ likex*, but omitsthe last word. 
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MODIFIERS 

After the optional word designator, you can add a sequenceof oneor more of the following modifiers, each preceded by a : 



h Remove a trai li ng pattinarne component, leavingonly the head. 

r R emove a trai lingsuffixof theform .m, leavingthebasename. 

e Remove ali but the trai li ngsuffix. 

t Removeall leading pathname componente leavingthetail. 

p Printthenew command but do not execute it. 

q Quote the substituted words, escaping further substitutions. 

x Quote the substituted words aswith q, but break into wordsat blanksand newlines. 

s/oi d/new/ Substitute n e w for the first occurrenceof oi t in theevent line. Any delimiter can beused in place of 

/.The final delimiter is optional if it isthelast character of theevent line. The delimiter may be 
quoted in old and new with a single backslash. If & appears in new, it isreplaced by oi d. A single 
backslash will quote the&. 

& Repeattheprevioussubstitution. 

g Causechangesto beapplied over the enti re event line. Thisisused in conjunction with :s (for 

example, :gs/oi d/new/) or :&. If used with :s, any delimiter can beused in placeof /, and the final 
delimiter is optional if it isthelast character of theevent line. 



ARITHMETIC EVALUATION 

Theshell allowsarithmetic expressi onsto beevaluated, under certain circumstances. (Seetheiet built-in command and 
"Arithmetic Expansion.") Evaluation isdonein long integers with no check for overflow, though division by 0 istrapped and 
flagged asan errar. The following list of operators isgrouped into levelsof equal-precedenceoperators. The la/els are listed 
in order of decreasi ng precedence. 

- + Unary minusand plus 

! " Logicai and bitwisenegation 

* /% M ultiplication, division, remainder 

+ - Addition, subtraction 

«» Left and right bitwiseshifts 

<= >= <> Comparison 

== != Equality and inequality 

& BitwiseAND 

BitwiseexclusiveoR 
] Bitwise or 

&& Logicai and 

Il Logicai or 

= •= /= %= += _= «= »=&=-=;= Assignment 

Shell variablesareallowed asoperands; parameter expansion isperformed beforetheexpression isevaluated. Thevalueof a 
parameter iscoerced to a long integer within an expression. A shell variableneed not haveits integer attri bute tu rned on to 
beused in an expression. 

Constantswith a leading 0 areinterpreted asoctal numbers. A leading 0x or m denotes hexadeci mal. Otherwise, numbers 
taketheform [b a s e #] n , where base is a decimai number between 2 and 36 representi ng the arithmetic base, and n isa 
number in that base. If base isomitted, then baselO isused. 



Operators are evaluated in order of precedence. Subexpressionsin parenthesesareevaluated first and may overridethe 
precedence rules. 
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SHELL BUILT-IN COMMANDS 

: [arguments ] 

. f il e ri a me [a r gu me n t s ] 
source f i I e ri a me [a r gu ment s ] 



alias [ria me [=val ue ] 



bg [j obspec ] 



bind [-m k e y ma p ] [-lvd] [ -q name] 
bind [ -m k e y ma p ] -f f i I ename 
bind [-m k e y ma p ] 

k e y s e g : f u n c t i o n • n a me 



break [n ] 



builtin s liei I - bui 1 1 i n [arguments] 



ed [di r ] 



N o effect; thecommand doesnothing beyond expanding arguments and performing 
any specified redi rections. A zero exit code isreturned. 
Read and executecommandsfrom fi i ename in thecurrent shell environment and 
return the exit status of the last command executed from f i i ename. If fi i ename does 
not contai n aslash, pathnamesin path areused to find the directory contai ni ng 
filename. Thefilesearched for in path need not beexecutable. Thecurrent directory 
issearched if no fileisfound in path. If any arguments are supplì ed, they becomethe 
positional parameterswhen file isexecuted. Otherwise, the positional parameters 
areunchanged. The return status is the status of the last command exited within the 
script (0 if no commands are executed), and False if filename is not found. 
alias with no arguments prints the list of aliases in theform name=vai ue on standard 
output. W hen arguments are supplied, an al ias i s defi ned for each namewhosevalue 
isgiven. A trai li ng space in valuecauses the next word to bechecked for alias 
substitution when the alias is expanded. For each namein theargument list for 
which no valueis supplied, the name and valueof the alias isprinted. alias returns 
True unless a name isgiven for which no alias hasbeen defined. 
Placej obspec in the background, asif it had been started with &. If j obspec isnot 
present, the shell 's noti on of thecurrent job isused. bg jobspec returns a unless run 
when job control isdisabled or, when run with job control enabled, if jobspec was 
not found or started without job control. 

D i splay current readiine key and function bindings, or bind a key sequenceto a 
readiine function or macro. The binding syntax accepted isi denti cai to thatof 
.inputrc, buteach binding must be passed as a separate argument; forexample, 
"\c-x\c-r": re-read-init-fiie. Options, if supplied, havethefollowing meanings: 
-m key ma p Usekeymap asthe keymap to be affected by the subsequent 

bindings. Acceptable key ma p names are emacs, emacs -standard, 
emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. 
vi ÌS equivalent tO vi-command; emacs ÌS equi valent tO emacs- 
standard. 

-1 List the names of ali readiine functions. 

-v List current function names and bindings. 

-d Dumpfunction namesand bindingsin such awaythatthey 

can be reread. 
-t filename Read key bindingsfrom filename 
-q function Q uery about which keys invokethe named function. 

The return valueiso unless an unrecognized option isgiven oran errar occurred. 
Exit from within a for, whiie, or untii loop. If n is specified, break n levels. n must 
bei. If n isgreater than thenumber of enclosing loops, ali enclosing loopsare 
exited. The return value is 0 unless the shell isnotexecutingaloopwhen breakis 
executed. 

Execute the specified shell builtin, passing it arguments, and return itsexit status. 
Thisisuseful when you wish to defi ne a function whose name is the sameas a shell 
builtin, but need the functional ity of the bui Iti n within the function itself. T he ed 
builtin iscommonly redefi ned thisway. The return status is False if shei 1 - bui 1 ti n is 
not a shell builtin command. 

Change the current directory to di r . The variable home is the default di r . The 
variablecDPATH defi nes the search path for the directory containi ng d r . Alternative 
directory names are separated by acolon (:). A nuli directory namein cdpath isthe 
sameas the current directory, that is, (.). If di r beginswith a slash (/), then cdpath is 
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command [-pVv] command [ a r g 



continue [n] 



declare [ -f rxi] [ n a me [=v a I ue ] ] 
typeset [ -f rxi] [n a me [=v a I ue ] ] 



dirs [-l][+/-n] 



echo [-neE] [ar g 



notused. An argument of- isequivalentto $oldpwd. The return valueismue ifthe 
directory was successfully changed; False otherwise. 

Run command with args suppressing the normal shell function lookup. 0 nly bui It- 
in commandsor commands found in thePATH areexecuted. If the-p option isgiven, 
thesearch for command isperformed using a default valuefor path that isguaranteed 
to find ali of the standard Utilities. If either the-v or -v option issupplied, a 
description of command is printed. T he -v option causesa singleword indicatingthe 
command or pathnameused to invoke command to be printed; the-v option 
produces a more verbose description. An argument of -disables option checkingfor 
therest of thearguments. If the-v or -v option issupplied, the exit status is 0 if 
command wasfound, and 1 if not. If neither option issupplied and an errar occurred 
orcommand cannot be found, the exit status is 127. Otherwise, the exit status of the 

command bui Iti n ÌS the exit Status Of c 0 mma nd . 

Resumé the next iteration of theenclosingtor, wniie, or untii loop. If n isspecified, 
resumé at the nth enclosing loop, n must bei. If n isgreaterthanthenumberof 
enclosing loops, thelast enclosing loop (the top- leve! loop) isresumed. The return 
valueiso unless the shell isnotexecutinga loop when continue isexecuted. 
D eclare vari ables and/or givethem attributes. If no namesaregiven, then display the 
values of vari ables i nstead. T he options can be used to restri et output to vari ables 
with thespecified attribute. 

-t U se function namesonly. 

-r M akenamesread-only. Thesenames cannot then beassigned 

values by subsequent assignment statemente. 

-x M ark namesfor export to subsequent commands via the 

environment. 

-i Thevariableistreated asan integer; arithmetic evaluation (see 

"Arithmetic Evaluation") is performed when thevariableis 
assigned a value. 

Using + i nstead of - turnsoff the attribute i nstead. W hen used in a function, makes 
names locai, aswith the locai command. The return valueiso unless an il legai 
option isencountered, an attempt ismadeto define a function using "-f foo=bar", 
oneof the names is not a legai shell variablename, an attempt ismadeto turn off 
read-only status fora read-only vari able, oran attempt ismadeto display a 
nonexistent function with -t. 

D i splay the list of currently remembered directories. D irectories are added to the list 
with thepusnd command; thepopd command moves back up through the list. 
+n D isplaysthe nth entry counting from the left of the list shown 

by dirs when invoked without options, starti ng with zero, 
-n D isplaysthe nth entry counting from the rightof the list 

shown by dirs when invoked without options, starti ng with 
zero. 

-1 Produces a longer listing; the default listi ng format uses a tilde 

to denote the home directory. 

The return valueiso unless an i I legai option issupplied orn indexes beyond the end 
of the directory stack. 

Output the args, separated by spaces. The return status isalwayso. If -n isspecified, 
the trai li ng newlineissuppressed. Ifthe -e option isgiven, interpretati on of the 
following backslash-escaped characters isenabled. The -e option disables the 
interpretation of these escape characters, even on systemswherethey are i nterpreted 
by default. 




\a 


Alert (beli) 


\b 


Backspace 


\o 


Suppresstrailing newline 


\f 


Form feed 


\n 


N ewline 


\r 


C arri age return 


\t 


H orizontal tab 


\v 


V erti cai tab 


\\ 


Backslash 


\n n n 


ThecharacterwhoseASCII code isn n n (octal) 



enabie [-n] [-allunarne ...] Enableand disable builtin shell commands. T hisallows theexecution of a disk 

command that hasthesamenameasashell builtin without specifyi ng a fui I 
pathname. I f -n isused, each nameisdisabled; otherwise, namesareenabled. For 
example, to use the test binary found viathePATH instead of the shell builtin versi on, 
typeenabie -n test. If no arguments are given, a list of ali enabled shell builtinsis 
printed. If only-n issupplied, a list of ali disabled builtinsis printed. If only-aii is 
supplied, the list printed i ncludes al I bui Iti ns, with an indication of whether or not 
each is enabled. enabie accepts-a asasynonym for -ali. The return valueise unless 
anameisnotashell builtin. 

evai [arg ...] T he args are read and concatenated together into a single command. T hiscommand 

isthen read and executed by the shell, and its exit status isreturned asthevalueof 
theevai command. If thereareno args, or only nuli arguments, evai returnsTrue. 

exec [[-] command [arguments]] If c omma nd isspecified, it replaces the shell. N o new process is created. T he arguments 

become the arguments to command. If the first argument is-, the shell placesadash in 
thezeroth arg passed to command. Thisiswhatiogm does. If thefilecannot be 
executed for some reason, a noninteractive shell exits, unless the shell variable 
no_exit_on_faiied_exec exists, in which caseit returns fai Iure. An interacti ve shell 
returns fai Iure if thefilecannot be executed. If command isnot specified, any 
redirections take effect in thecurrent shell, and the return status ise. 

exit [n] C ause the shell to exit with a status of n . If n is omitted, the exit status isthat of the 

last command executed. A trap on exit isexecuted before the shell terminate. 

export [-nf ] [name [=wor d ] ] ... T he suppl ied names are marked for automatic export to the envi ronment of 

export -p subsequently executed commands. If the -f option isgiven, the names referto 

functions. If no names are given, or if the -p option issupplied, a list of ali names 
that are expo rted in this shell i s printed. The -n option causes the export property to 
beremoved from thenamed variables. An argument of - disables option checking 
for the restof the arguments. export returns an exit status of a unless an illegal 
option is encountered, one of the names is not a legai shell variable name, or -f is 
supplied with a namethat isnot afunction. 

te [-e ename ][-nir] [fi rst ][i ast : Fixcommand. I n the first form, a rangeof commands from fi rst to i a s t isselected 

te -s [pat=rep][cmd] from the history list, f i r st and i ast may be specified as a stri ng (to locate the last 

command beginning with that stri ng) or asa number (an index into the history list, 
where a negative number isused asan offset from thecurrent command number). If 
ast isnot specified, itis setto thecurrent command for listing (so that te -1 
-10 prints the last 10 commands) and to first otherwise. If first isnot specified, it 
i s set to the previous command for editing and -16 for listing. 
The-n flag suppresses the command numberswhen listing. The -r flag reversesthe 
order of the commands. If the -1 flag isgiven, the commands are listed on standard 
output. Otherwise, the editor given byename isinvoked on afilecontainingthose 
commands. If ena me is not given, the value of the fcedit variable is used, and the 
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fg [j obs pec ] 



getopts o p t s t r i n g name [ a r g s ] 



hash [-r][name] 



help [pattern] 



valueof editor if fcedit is not set. Ifneither vari ableis set, vi isused. W hen editing 

is complete, the edited commands are echoed and executed. 

In the second form, comma nd isreexecuted after each instanceof pat isreplacedby 

r e p . A useful alias to use with this is r=f c -s, so thattyping r ce runsthe last 

command beginning with ce and typing r reexecutes the last command. 

If the first form isused, the return value iso unless an illegal option isencountered 

orti r s t ori ast specify history linesout of range. I f the -e option is supplì ed, the 

return value is the value of the last command executed orfailureif an errar occurs 

with thetemporary file of commands. If the second form isused, the return status is 

that of the command reexecuted, unlesscmd does not specify a valid history line, in 

which casetc return sfai Iure. 

Placej obspec in theforeground, and makeitthecurrentjob. If j obspec isnot 
present, the shell's notion of thecurrent job isused. The return value is that of the 
command placed into theforeground, orfailureif run when job control isdisabled 
or, when run with job control enabled, if j obspec does not specify a valid job or 
i obspec specifies a job that wasstarted without job control, 
getopts isused by shell proceduresto parse positional parameters. optstri ng contai ns 
theoption lettersto berecognized; if aletter isfollowed by acolon, theoption is 
expected to havean argument, which should beseparated from it by whitespace 
Each timeit isinvoked, getopts placesthenext option in the shell vari able name, 
initializingname if it does not exist, and the index of the next argument to be 
processed into the vari able optind. optind isinitialized to 1 each timethe shell or a 
shell script is invoked. When an option requiresan argument, getopts places that 
argument into the vari able optarg. The shell does not reset optind automati cai ly; it 
must bemanually reset between multiple Calisto getopts within the same shell 
invocation if a new set of parameters i sto beused. 

getopts can report errors in two ways. If the first character of optstri ng is a colon, 
silent errar reporting isused. In normal operation, diagnostic messagesareprinted 
when illegal options or missing option argumentsareencountered. If thevariable 
opterr is set to 0, no errar messagewill bedisplayed, even if the first character of 
optstri ng isnotacolon. 

If an illegal option isseen, getopts places a question mark (?) into nane and, if not 

silent, printsan errar messageand unsets optarg. If getopts issilent, theoption 

character found isplaced in op-targ and no diagnostic messageisprinted. 

If a required argument is not found, and getopts isnot silent, a question mark (?) is 

placed in name, optarg isunset, and a diagnostic messageisprinted. If getopts is 

silent, then acolon (:) isplaced in name and optarg i s set to theoption character 

found. 

getopts normally parses the positional parameters, but if more arguments are given 
in args, getopts parsesthoseinstead. getopts returnsTrue if an option, specified or 
unspecified, is found. It returns False if the end of options isencountered or an error 
occurs. 

Foreach name, the fui I pathnameof the command isdetermined and remembered. 
The -r option causes the shell to forget ali remembered locations. If no arguments 
are given, information about remembered commands isprinted. An argument of - 
disables option checking for the rest of the arguments. The return status isTrue 
unless a name isnot found oran illegal option issupplied. 
D i splay helpful information about built-in commands. If pattern is specified, heip 
gives detai led help on ali commands matching pattern; otherwise, a list of the 
builtins isprinted. The return status is 0 unless no command matches pattern. 




With no options, display the command history list with linenumbers. Lines li sted 
with a* havebeen modified. An argumentof n listsonly thelastn lines. If a 
nonoption argument is supplì ed, it isused as the nameof the history fi le; if not, the 
valueof histfile isused. Options, if supplied, nave the following meanings: 

-a Append the"new" history lines (history linesentered sincethe 

beginning of thecurrent basb sessi on) to the history file, 
-n Read the history lines not al ready read from the history file 

into thecurrent history list. These are lines appended to the 
history fi le sincethe beginning of the current basti session. 
-r Read thecontentsof the history fi le and usethem asthe 

current history. 

w- Write the current history to the history file, overwritingthe 

history file's contents. 

The return valueise unlessan il legai option isencountered oranerroroccurswhile 
readi ng or writi ng the history file. 

The first form lists the activejobs. T he -1 option lists processi D sin addition to 
the normal i nformation; the -p option lists only the process I D of the job's process 
group leader. The-n option displaysonlyjobsthathavechanged status si n ce last 
notified. If j obspec isgiven, output isrestricted to information aboutthatjob. The 
return status ise unlessan illegal option isencountered or an II legai j obspec is 
supplied. 

If the -x option is supplied, jobs replacesanyj obspec found in command orargs with 
thecorresponding process group I D , and executes command, passi ng itargs, returni ng 
its exit status. 

Send thesignal named by sigspec to theprocessesnamed by pi d or] obspec . si gspec 
is either a si gnal namesuch assiGKiLL or a signal number. If si gspec isasignal 
name, thenameis not case sensitive and may be given with or without thesiG 
prefix. If sigspec isnot present, then sigterm isassumed. An argument of -1 lists the 
signal names. If any arguments are supplied when -1 isgiven, thenamesof the 
specified signals are listed, and the return status is 0. An argumentof - disables 
option checkingfor therest of the arguments. km returnsTrue if at leastone signal 
wassuccessfully sent, orFaise if an errar occurs or an illegal option isencountered. 
Each arg isan ari thmetic expression to beevaluated. (See "Arithmetic Evaluation.") 
If the last a r g evaluatesto 0, iet returns 1; 0 isreturned otherwise. 
Foreach argument, createa locai variablenamed name, and assign itvai uè. When 
locai isused within afunction, it causesthevariablenameto havea visible scope 
restri cted to that function and itschildren. With no operands, locai writesa list of 
locai variablesto the standard output. It isan errorto use locai when not within a 
function. The return status i s 0 unless locai isused outside a function, or an illegal 
name is supplied. 
Exit a logi n shell. 

Removesentriesfrom the directory stack. W ith no arguments, removesthetop 
directory from the stack, and performsacd to thenew top directory. 

+n Removesthenth entry counti ng from theleft of the list shown 

by dirs, starti ng with zero. Forexample, popd +0 removesthe 
first directory, popd +1 thesecond. 
-n Removesthenth entry counti ng from theright of the list 

shown by dirs, starti ng with zero. For example, popd -0 
removesthe last directory, popd -1 thenextto last. 
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If the popd command issuccessful, a dirs isperformed aswell, and the return status 
isa. popd returnsFaise if an illegal option isencountered, the directory stack is 
empty, a nonexistent directory stack entry isspecified, or the directory changefails. 
pushd [dir] pushd +/-n Adds a directory to the top of the di rectory stack, or rotates the stack, maki ng the 

new top of the stack the current working directory. With no arguments, exchanges 
thetoptwo di recto ri es and returnse, unlessthedirectory stack isempty. 

+n Rotates the stack so that thenth directory (counti ngfrom the 

leftof the list shown bydirs) isatthetop. 
-n Rotates the stack so that thenth directory (counti ngfrom the 

right) isatthetop. 

dir Addsdir to the directory stack at the top, making it the new 

current working directory. 

If the pushd command issuccessful, adirs isperformed aswell. If the first form is 
used, pushd returnso unlessthecd to di r fails. W ith thesecond form, pushd returnso 
unlessthedirectory stack isempty, a nonexistent directory stack element isspecified, 
or the di rectory changeto thespecified new current directory fails. 
pwd Print the absolute pathnameof the current working directory. The path printed 

contai ns no symbolic links if the -p option to the set bui Iti n command is set. (See 
also the descri ption of noiinks under "Shell Vari ables," earlier in thismanual page.) 
The return status is 0 unlessan errar occurswhilereadingthepathnameof the 
current di rectory. 

read [-r][name ...] 0 ne line is read from the standard input, and the first word is assigned to the first 

name, thesecond word to thesecond name, and so on, with leftover words assigned 
to thelast name. Only thecharactersin ifs arerecognized asword delimiterà If no 
namesaresupplied, the line read is assigned to the vari ableREPLY. The return codeis 
zero, unlessend-of-file isencountered. If the -r option isgiven, a backslash-newline 
pair isnot ignored, and thebackslash isconsidered to be part of theline. 

readoniy [-funame ...] Thegiven names are marked readoniy and the valuesof these names may not be 

readoniy -p changed by subsequentassignment. Ifthe-f option issupplied, thefunctions 

correspondingto the names are so marked. If no arguments are given, or if the 
-p option issupplied, a list of ali readoniy names is printed. An argument of - 
disables option checking for the rest of the arguments. The return status ise unless 
an illegal option isencountered, oneof the names isnot a legai shell variablename, 
or-t issupplied with anamethatisnotafunction. 

return [n ] C auses a function to exit with the return value specified by n . If n isomitted, the 

return status is that of thelast command executed in the function body. If used 
outside a function, butduringexecution of a script by the . (source) command, it 
causes the shell to stop executing that script and return either n or the exit status of 
thelast command executed within the script as the exit status of the script. If used 
outside a function and notduringexecution of a seri pt by (. , the return status is 

False. 

set [ — abef hkmnptuvxldCHP] 
[ -0 option] [arg . . . ] 

-a Automatically mark vari ables that are modified or created for 

export to theenvironment of subsequent commands. 

-b C ause the status of termi nated background jobsto bereported 

immediately, ratherthan beforethenext primary prompt. 
(Also see notify under "Shell Vari ables.") 

-e Exit immediately if a simple command (see "Shell Grammar," 

earlier in thismanual page) exitswith a non- zero status. The 
shell does not exit if the command that fails is part of an untii 




orwhiie loop, part of an if statement, part of a&& or \ ; list, or 
if thecommand's return valueisbeing inverted via \. 
-f Disablepathnameexpansion. 

-h Locate and rememberfunction commandsasfunctionsare 

defined. Function commandsarenormally looked upwhen 
thefunction isexecuted. 

-k Ali keyword argumentsareplaced in theenvironmentfora 

command, not just thosethat precede thecommand name. 

-m M onitor mode. Job control isenabled. Thisflag ison by 

default for interactiveshellson systemsthat support it. (See 
"Job Control," earlier in thismanual page.) Background 
processesrun in a separate processgroup and alinecontaining 
their exit status isprinted upon theircompletion. 

-n Read commandsbut do not executethem. This may beused 

to check ashell seri pt for syntax errors. Thisisignored for 
interattive shells. 

-o opti on- name Theopti on- name can be one of the following: 
aiiexport— Same as -a. 

braceexpand— Theshell performs brace expansion. (See"Brace 
Expansion," earlier in thismanual page.) This ison by default, 
emacs— U se an emacs-style command lineediting interface. 
This isenabled by default when theshell isinteractive, unless 
theshell isstarted with the -noiineediting option. 

errexit— SameaS-e. 

histexpand— Same as -H. 

ignoreeof— Theeffect isasif theshell command 

■ ignoreeof=i8 had been executed. (See "Shell Variables.") 

interactive-comments— Allow aword beginning with # to 

cause that word and ali remainingcharacterson that lineto be 

ignored in an interattive sh eli. (See"Comments," earlier in 

thismanual page.) 

monitoi — Same as -m. 

nociobber— Sameas-c. 

noexec— Sameas -n. 

nogiob— Sameas-f. 

nohash— Sameas -d. 

notify— Sameas-b. 

nounset — Same as -u. 

physicai— Sameas -p. 

posix— C hange the behavior of bash where the default 
operation differsfrom the POSIX 1003.2 standard to match 
the standard, 
privileged — Same as -p. 
verbose— Sameas-v. 

vi— U se a v i- sty I e co m m an d I i n e ed i ti n g i n terf ace. 
xtrace— Sameas -x. 

If no opt i on- name issupplied, the values of the current opti ons 
areprinted. 



-p Turn on privi leged mode. In thismode, the$ENv file is not 

processed, and shell functionsarenot inherited from the 
environment. This isenabled automati cally on startup if the 
effective user (group) I D is not equal to the real user (group) 
ID . T urni ng this option off causes the effective user and group 
I D s to be set to the real user and group I D s. 

-t Exit after reading and executing onecommand. 

-u Treatunset variablesasan errar when performing parameter 

expansion. If expansion isattempted on an unset variable, the 
shell prints an errar message, and, if not interactive, exitswith 
a non- zero status. 

-v Printshell input linesasthey areread. 

-x After expandi ngeach simplecommand, basti displaysthe 

expanded valueof PS4, followed by thecommand and its 
expanded arguments. 

-ì Save and restare the bindingof name in a f or name [in word] 

command. (See "Shell Grammar," earlier in thismanual page.) 

-d Disablethehashingof commandsthatarelooked upfor 

execution. Normally, commandsareremembered in ahash 
table, and oncefound, do not haveto be looked up again. 

-c Theeffect isasif the shell command nociobber= had been 

executed. (See "Shell Variables.") 

-h Enable ! style history substitution. T his flag is on by default 

when the shell is interactive. 

-p If set, do notfollow symbolic links when performing 

commandssuch ascd that changethecurrent directory. The 
physical directory isused instead. 

If no arguments follow thisflag, then the positional parameters 
are unset. Otherwise, the positional parameters are setto the 
args, even if someof them begin with a-. 
Signal theend of options, causeall remai ni ng args to be 
assignedto the positional parameters. The -x and -v options 
areturned off. If there are no args, the positional parameters 
remain unchanged. 

Theflagsareoff by default unless otherwise noted. Using + 
rather than - causes these f lags to be turned off. T he f lags can 
also bespecified as options to an invocation of the shell. The 
currentset of flagsmay befound in $-. After the option 
arguments are processed, the remai ni ngn args aretreated as 
valuesfor the positional parameters and areassigned, in order, 
to $1, $2, ... $n. If no options or args are supplied, ali shell 
variables are printed. The return status isalwaysTrue unless an 
il legai option isencountered. 

The positional parameters from n+1 . . . are renamed to . . . . Parameters represented 
by thenumbers$# down to $#-n+i are unset. If n is a, no parameters are changed. If 
n isnot given, it isassumed to bei. n must bea non-negative num ber lessthan or 
equal to $#. If n isgreaterthan $#, the positional parameters are not changed. The 
return status isgreaterthan 0 if n isgreaterthan or lessthan 0; otherwisee. 
Suspend theexecution of this shell until it receivesa sig-cont signal. The-f option 
says not to compiai n if this is a ìogin shell; just suspend anyway. The return status is 




a unless the shell isa ìogin shell and -f isnot supplied, or if job control isnot 
enabled. 

test expr[expr ] Return a status of 0 (True) or 1 (False) depending on thee/aluation of the 

conditional expression expr. Expressions may beunary or binary. U nary expressions 
areoften used to exam ine the status of a file There are stri ng operatorsand numeric 
compari son operato rsaswél. Each operator and operand must bea separate 
argument. If fileisof theform /dev/fd/n, then fi le descriptor n ischecked. 



-b f 


I e 


— Tn ip if f i i p exi sK and is block snpcial 

I I U C I 1 1 1 1 C C/VI JLJ Ul IU 1 3 U 1 U V_l\ 3[JO_l Ul . 


-c f 


I e 


mi io if f i I o pyì ere anH i c rharartpi* cnpri al 

— 1 I u e 1 1 1 1 1 e CAI jlj al 1 u 1 o LI lai aLLCI o|J CLI al . 


-d f 


I e 


Tn ip if f i i e pxi sts and isa Hi rprtnrv 

1 1 U U 1 1 1 1 1 t CAI jl j ai 1 u J □ UN CLLU 1 y . 


-e f 


I e 


Trnp if f i 1 e PXÌ Sf~S 

1 1 U C 1 1 1 1 1 C CAI JL Di 


-f f 


I e 


— True if f ì i e exists and is a regular file. 


-g f 


I e 


— True if f m e exists and is set-group-id. 


-k f 


I e 


— Trueiffiie has its "sticky" bit set. 


-L f 


I e 


— True if f i i e existsand isa symbolic link. 


-P f 


I e 


— True if f m e existsand isa named pipe. 


-r f 


I e 


-True if f i i e existsand isreadable. 


-s f 


I e 


— True if f i i e existsand hasasizegreaterthan zero. 


-S f 


I e 


— True if f m e existsand isa socket. 


-t fd — 


True if f d isopened on a terminal. 


-u f 


I e 


— True if f m e existsand itsset-user-id bit is set. 


-w f 


I e 


— True if f m e existsand is writable. 


-X f 


I e 


— True if f i i e exists and is executable. 


-0 f 


I e 


— True if f m e existsand isowned by theeffectiveuserID. 


-G f 


I e 


— True if f m e existsand isowned by theeffectivegroup ID 



fi lei -nt fi i e 2 — True if f i i e i is newer (accordi ng to modificati on date) than 

fi I e 2 . 

f i I el -ot fi I e 2— True if f i I el isolder than fi I e 2 . 

f i i ei -et fi i e— True if f m ei and f i i e 2 have the same device and inode 
numbers. 

-z stri ng — True if the length Of stri ng iszero. 

■ n stri ng — True if the length of stri ng isnon-zero. 
stri ngi = stri ng2— True if the strings are equal. 
stri ngi != stri n g 2 — True if the stri ngs are not equal. 

! expr — True if expr ÌSFalse. 

ex p r 1 -a ex pr 2 — True if both exprl AND e x p r 2 are True. 
exprl -o expr 2— True if either expr 1 OR e x p r 2 ÌSTrue. 

ergi op a r g 2 op isoneof -eq, -ne, -ìt, -le, -gt, or -ge. These ari thmetic binary 
operators return True if argi isequal, not-equal, less-than, less-th an-or-equal, 
greater-than, or greater-than-or-equal than a r g 2 , respectively. a r g 1 and a r g 2 may 
be positive integers, negative in tegers, or the special expression -1 stri ng, which 
evaluatesto the length ofstri ng. 

times Printtheaccumulated user and system ti mesfor the shell and for processesrun from 

the shell. T he return status isa. 
trap [-1] [erg] [si gspec ] T he command a r g is to be read and executed when the shell receives signal(s) 

si gspec . If ar g isabsent or-, ali specified signals are reset to their originai values(the 
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values they had upon entranceto the shell). If a r g isthenull stri ng, thissignal is 
ignored by the shell and by the commands iti nvokes. si gspec is either a si gnal name 
defined in <signai.h>, orasignal number. If si gspec is exit (0), thecommand a r g 
isexecuted on exitfrom theshell. With no arguments, trap prints the list of 
commands associ ated with each si gnal number. The-i option causes the shell to 
print a list of signal namesand their corresponding numbers. An argument of - 
disables option checking for the restof the arguments. Si gnals ignored upon entry to 
theshell cannot betrapped or reset. T rapped signals are resetto their originai values 
in achild processwhen it iscreated. The return statusisFaise if either the trap name 
or number isinvalid; otherwise, trap returnsTrue. 
type [-aii][-type | -patti] W ith no options, indicate how each namewould be interpreted if used as a 

name [name ...] command name. If the -type flag is used, type prints a phrase that is one of alias, 

keyword, tunction, buiitin, or file if nane is an alias, shell reserved word, function, 
builtin, or disk file, respectively. If the name isnotfound, then nothing isprinted, 
and an exit status of False isreturned. If the -path flag isused, type either returns 
the name of the disk fi le that would beexecuted if name werespecified asacommand 
name, or nothing if -type would not return file. If a command is hashed, -path 
prints the hashed value, not necessari ly the fi le that appears first in path. If the-aii 
flag isused, type prints ali of the places that contai n an executablenamed name.This 
includes aliases and functions, if and only if the -path flag isnotalso used. Thetable 
of hashed commands is not consulted when using -ali. type accepts -a, -t, and -p in 
placeof -ali, -type, and -path, respectively. An argument of - disablesoption 
checki ng for the rest of the arguments. type returns True if any of the arguments are 
found, False if none are found. 
uiimit [-SHacdfmstpnuv [li mi t ] : uiimit provides control over the resources available to theshell and to processes 

started by it, on systemsthat allow such control. The value of umit can bea number 
in theunit specified fortheresource, or the value uniimited. The h and s options 
specify that the hard or soft limit is set for the given resource. A hard limit cannot be 
increased onceit isset; a soft limit may beincreased up to the value of the hard 
limit. If neither h nor s is specified, thecommand appliesto the soft limit. If limit is 
omitted, the current value of the soft li m it of the resource i s pri nted, unless the h 
option is given. When morethan one resource is specified, theiimit name and unit 
isprinted befo re the value. Otheroptionsareinterpreted asfollows: 



-a Ali current limits are reported. 

-c Themaximum sizeof corefilescreated. 

-d Themaximum sizeof a process's data segment. 

-t Themaximum sizeof fi lescreated by the shell . 

-m Themaximum resi dent set size 

-s Themaximum stack size. 

-t Themaximum amountof cputimein seconds. 

-p Thepipesizein 512-byte blocks. (Thismay not beset.) 

-n Themaximum number of open filedescriptors. (M ostsystems 

do not allow this value to beset, only displayed.) 

-u Themaximum numberof processes avai lableto a single user, 

-v Themaximum amountof virtual memoryavailabletothe 

shell. 



An argument of - disablesoption checking for the restof thearguments. If limit is 
given, it isthenew value of the specified resource (the -a option isdisplay only). If 
no option is given, then -f isassumed. Values are in 1024-byte incrementi except 
for-t, which isin seconds; -p, which isin unitsof 512-byte blocks; and -n and -u, 




which are unscaled values. The return status is 0 unlessan illegai option isencoun- 
tered, a non-numeric argument other than uniimited is supplì ed asiimit, or an errar 
occurswhilesettinganew limit. 

umask [-s][mode] The user file-creation mask issetto mode. If mode beginswith a digit, it isinterpreted 

asan octal number; otherwise, it isinterpreted asasymbolic mode mask similar to 
that accepted by chmod(l). If modeisomitted, or if the-s option issupplied, the 
currentvalueof the mask isprinted. The-s option causesthemask to beprinted in 
symbolicform; the default output isan octal number. An argument of - disables 
option checkingfor therest of the arguments. The return status is 0 if the mode was 
successfully changed or if no mode argument was supplied, and False otherwise. 

unaiias [-a] [narra ...] Remove names from the list of defined aliases. If -a is supplied, ali alias definitions 

areremoved. The return value isTrue unless a supplied nameis nota defined alias. 

unset [-fv][name ...] For each name, remove the corresponding variable or, gi ven the -f option, function. 

An argument of - disablesoption checkingfortherestofthearguments. Note that 
path, ifs, ppid, psi, ps2, uid, and euid cannot be unset. If any of random, seconds, 
lineno, or histcmd are unset, they lose their special properties, even if they are 
subsequently reset. The exit status is True unless a namedoes not exist or isnon- 
unsettable. 

wait [ni W ait for the specifi ed process and return its termi nati on status, n may be a process 

ID or a job specification; if a job spec isgiven, ali processesin that job's pipeline are 
waited for. If n is not given, ali currently activechild processesarewaited for, and the 
return status is zero. If n specifiesa nonexistent process orjob, thereturn status is 
127. Otherwise, thereturn status is the exit status of the last process or job waited 
for. 



INVOCATICI 

A login shell isonewhose first character of argumentzero isa-, oronestarted with the-iogin flag. 

An interactive shell isonewhose standard input and output are both connected toterminals(asdetermined by isatty(3)), or 
onestarted with the-i option. psi isset and includesi if basti is interactive, allowing a shell script or astartup fileto test this 
state. 

Login shells: 

On login (subject to the -noprofile option): 
if /etc/profile exists, source it. 
if "/.bash_profile exists, source it, 
else if "/.bash_login exists, source it, 
else if "/.profile exists, source it. 
On exit: 

if "/ .bash_logout exists, source it. 
Non-login interactive shells: 

On startup (subject to the -norc and -refile options): 
if "/.bashrc exists, source it. 
Non-interactive shells: 
On startup: 

if the environment variable ENV is non-nuli, expand 

it and source the file it names, as if the command 

if [ "$ENV" ]; then . $ENV; fi 

had been executed, but do not use PATH to search 

for the pattinarne. When not started in Posix mode, bash 

looks for BASH ENV before ENV. 



If Bash isinvoked assh, it tristo mimiethebehavior of sh as closely aspossi ble. For a login shell, it attemptsto source only / 
etc/profiie and "/.profile, in that order. The-noprome option may stili beused to disablethis behavior. A shell invoked 
as sh does not atterri pt to source any other startup fi les. 
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When bash i s started in posix mode, aswith the-posix command lineoption, itfollowsthe POSIX standard forstartup files. 
In thismode theENv variableisexpanded and that file sourced; no other startup files are read. 

SEEALSO 

Bash Features, Brian Fox and ChetRamey 

TheGnu Readline Library, Brian Fox and Chet Ramey 

TheGnu H i story Library, Brian Fox and Chet Ramey 

A SystemV Compatirei mplementation of 4.2BSD Job Control, David Lennert 

PortableOperating System Interface (POSIX) Part 2: Shell and Utilities, IEEE 

sh(l), ksh(l), csh(l), emacs(l), vi(l) readline(3) 

FILES 

/bin/bash T he bash executable 

/etc/profiie Thesystemwide i n iti al izati on file executed for login shells 

/.bash_profiie The personal i n iti al izati on file, executed for login shells 

/.bashrc T he individuai per- i n teracti ve- sh el I startup file 

/.inputrc Individuai readline i n i ti al i zati on file 

AUTHORS 

Brian Fox (Free Software Foundation; primary author; bfox@ai.MiT.Edu), Chet Ramey (Case Western Reserve U ni versity; 

chet@ins.CWRU.Edu) 

COPYRIGHT 

Copyright© 1989, 1991 by the Free Software Foundation, Inc. 
BUG REPORTS 

If you find a bug in bash, you should report it. But first, you should makesurethat it really isa bug, and that it appearsin 
the latest version of bash that you nave 

Once you h ave determi ned that a bug actually exists, mail a bug report to bash-maintainers@prep.ai.M IT.Edu. If you havea 
fix, you are welcome to mail that aswell! Suggestionsand "philosophical" bug reports may bemailed to bug- 

bash@prep.ai.MIT.Edu Or pOSted tO the Usenet newsgroup gnu. bash. bug. 

ALL bug reports should include the following: 

The version numberof bash 

The hardware and operati ng system 

Thecompiler used to compile 

A descri ption of the bug behavior 

A short script or "recipe" that exercises the bug 

Commentsand bug reports concerningthismanual page should bedirected to chet@ins.cwru.edu. 

BUGS 

It'stoo big and too slow. 

Therearesomesubtledifferences between bash and traditi onal versionsof sh, mostly becauseof the posix specificati on. 
Aliasesareconfusing in someuses. 

GNU, 9 March 1995 



beforelight 

bdftopcf 

bdftopcf— Convert X fontfrom Bitmap D istri bution Formatto Portable Compilai Format 
SYNOPSIS 

bdftopcf [ -pn ][-un ][-m ][-l ][-M ][-L ][-t ][-i ][-o o u t puffi I e ] fontfile.bdf 

DESCRIVO N 

bdftopcf isafont compi ler forthex server and font server. Fontsin Portable Compi led Format can beread by any 
architecture, although thefi le is structured to allow one parti cular are hitectu reto read them directly without reformatti ng. 
T his allows fast reading on the appropriate machine, but the fi les are stili portable (but read moreslowly) on other machines. 

OPTIONS 

-pn 

-un 

-m 
-1 
-M 
-L 
-t 



-o outpjt-file-name 

SEEALSO 

x(D 

AUTHOR 

Keith Packard, M IT X Consortium 

X Versi on 11 Release 6 

beforelight 

beforeiight— Screen saver 
SYNOPSIS 

beforelight [ — toolkitoption ... ] 



Sets the font glyph paddi ng. Each glyph in the font wi II haveeach scarnine padded in to a multiple 
of n bytes, where n is 1, 2, 4, or 8. 

Sets the font scanli ne unit. W hen the font bit order isdifferent from the font byteorder, the 
scanlineunitn descri bes what unit of data (in bytes) areto beswapped; the unit i can bel, 2, or4 
bytes. 

Sets the font bit order to msb (most significant bit) first. Bitsforeach glyph will beplaced in this 
order; that is, the leftmost bit on the screen will bein the highest valued bit in each unit. 
Sets the font bit order to lsb (least significant bit) first. The leftmost bit on the screen will bein the 
lowest valued bit in each unit. 

Setsthefont byteorder to msb first. Ali multi byte data in thefile {metrics, bitmaps, and everything 
else) will bewritten most significant byte first. 

Setsthefont byteorder to lsb first. Ali multi byte data in thefile (metrics, bitmaps, and everything 
else) will bewritten least significant byte first. 

When thisoption isspecified, bdftopcf will convert fontsinto terminal fontswhen possi ble A 
terminal font haseach glyph image padded to thesamesize; thex server can usuai ly render these 
types of fonts more quickly. 

Thisoption inhibitsthenormal computation of ink metrics. When a font has glyph imagesthat do 
notfill the bitmap image (that is, the"on" pixels don't extend to the edgesof the metrics), bdftopcf 
computestheactual ink metrics and placesthem in the pcf file; the-t option inhibitsthisbehavior. 
By default bdftopcf writesthepcF fileto standard output; thisoption givesthenameof afileto be 
used instead. 
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Thebeforeiight program isasampleimplementation of ascreen saver forx servers supporti ng the mit-screen -saver 
extension. 

AUTHORS 

Keith Packard (M IT X Consortium) 

X Versi on 11 Re!ease6 

biff 

biff— Be noti fi ed if mail arrives and who it isfrom 
SYNOPSIS 

biff [ny] 

D ESC RIPTIO N 

biff informsthe system whetheryou wantto benotified when mail arrives during the current terminal session. 

0 ptions supported by biff: 

n D isables notification 

y Enables notification 

When mail notification isenabled, theheader and first few linesof themessagewill beprinted on your screen whenever mail 
arrives. A 
biff y 

command isoften included in thefile .ìogin or .profile to beexecuted ateach login. 

Biff operatesasynchronously. For synchronous notification use the mail vari ableof sh(l) or the mail variableof csh(l). 
SEEALSO 

csh(l), mail(l), sh(l), comsat(8) 

HI STORY 

Thebitf command appeared in BSD 4.0. 

BSD 4, 14 March 1991 

bioradtopgm 

bioradtopgm— Convert a Biorad confocal fileinto a portablegraymap 
SYNOPSIS 

bioradtopgm [ -image#] [i ma g e d a t a ] 

DESCRIPTION 

Reads a Biorad confocal fi le as input. Produces a portablegraymap as output. If the resulti ng imageisupsidedown, run it 
through pnmtiip -tb. 
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OPTIONS 

-image# A Biorad i mage fi le may contai n morethan oneimage. With thisflag, you can specify which imageto 

extract (only one at a ti me). The first i mage in the fi le has number zero. If no image number is supplì ed, 
only information about the image size and the number of images in the input is printed out. N o output is 
produced. 

BUGS 

A Biorad image may be in word format. If PbmPius isnot compi led with theBiGGRAYs flag, word filescannot beconverted. See 
the makefile. 

SEEALSO 

pgm(5), pnmflip(l) 

AUTHORS 

Copyright© 1993 by 0 liverTrepte 

28 Junel993 
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bitmap, bmtoa, atobm— Bitmap editor and converter utilitiesfor theX Window System 
SYNOPSIS 

bitmap [ -opti o n s . . . ] [f i I ena me ] [ b a s e n a me ] 
bmtoa [ -chars . . . ] [f i I ena me ] 

atobm [ -chars c c ] [-name vari a b I e ] [-xhot number ] [-yhot n umber ] [ f t I e n a me ] 

DESCRIPTION 

The bitmap program isa rudimentary tool for creati ng or editing rectangular images madeup of lsand Os. Bitmapsareused 
in x for defi ni ng clipping regions, cursor shapes, icon shapes, and ti le and stipple patterns. 

The bmtoa and atobm filters convert bitmap files {file format) to and from ASCII strings. They aremost commonly used to 
quickly printout bitmaps and to generate versions for includi ng in text. 

COMMAND-LINE OPTIONS 

Bitmap supports the standard X Tool kit command-linearguments; see x(l). The following addi tional argumentsare 
supported aswell: 

Specifies size of the grid in squares. 
Specifies the width of squaresin pixels. 
Specifies the height of squares in pixels. 

Grid tolerance If the square d i mensi ons fall below the specified value, grid will be 
automatically turned off. 
Turnson or off thegrid lines. 
Turnson or off the major axes. 
Turnson or off dashingfortheframeand grid lines. 
Turnson or off stippling of highlighted squares. 



-size Wl DT Hx HE I GHT 
-sw rj 
-sh rj 
-gt rj 



me n s i o n 
me n s o n 
me n s i un 



-grid, tgrid 
-axes, +axes 
-dashed, +dashed 
-stippled, +stippled 



Turns proportional modeon or off. If proportional modeison, squarewidth is 

equal to square height. If proportional mode is off, bitmap will usethesmaller square 

dimension, if they were i n i ti al ly different. 

Specifi es the bitmap to beused as a stipplefor dashing. 

Specifi es the bitmap to beused as a stipplefor highlighting. 

Specifi es the color used for highlighting. 

Specifi es the color used for the f rame and grid lines. 

Specifi es the bitmap to be i n iti al ly loaded into the program. If the file does not exist, 
bitmap will assume it is a new file. 

Specifi es the basenameto beused in theC code output fi le. If it is different than the 
basenamein the working fi le, bitmap will changeitwhen savingthefile. 

Thisoption specifies the pai r of charactersto use i n the string version of the bitmap. 
The first character isused for 0 bitsand thesecond character isused for 1 bits The 
default isto usedashes(-) forOsand number signs (#) for ls. 



Thisoption speci fi es the pai rof charactersto usewhen converti ng string bitmaps 
into arraysof numbers. The first character representsa 0 bit and thesecond 
character representsa 1 bit. The default isto usedashes(-) forOsand number signs 
(#) for ls. 

Thisoption specifies the vari ablenameto beused when writing out the bitmap file. 
Thedefault isto usethebasenameof thefilenamecommand-lineargument or leave 
it blank if the standard input isread. 

Thisoption specifies the X coordinateof the hot spot. 0 nly positi ve vai ues are 
allowed. By default, no hot spot information isincluded. 
Thisoption specifies the Y coordinateof the hot spot. Only positive vai ues are 
allowed. By default, no hot spot information isincluded. 

USAGE 

bitmap displaysgrid in which each square representsa single bit in the picture being edited. Actual sizeof the bitmap image, 
asit would appear normally and inverted, can beobtained by pressing M eta-l. You arefreeto move the image pop-up out of 
thewayto continue editing. Pressing the left mouse button i n the pop-up window or Meta-I againwill remove the real size 
bitmap image. 

If the bitmap isto beused for def i ni ng acursor, oneof thesquaresin theimagesmay bedesignated as the hot spot. This 
determi neswhere the cursor is actual ly pointing. For cursorswith sharp tips(such asarrowsor fingers), this is usually atthe 
end of the tip; forsymmetric cursors(such ascrossesor bulls-eyes), this is usually at the center. 

Bitmaps are sto red assmall C code fragmentssuitable for includi ng in applications. They provi de an array of bitsaswell as 
symbolic constants givi ng the width, height, and hot spot (if specifi ed) that may beused in creati ng cursors, icons, and tiles. 

EDITING 

To edita bitmap image, simply click on oneof the buttonswith drawing commands(Point, Curve, Line, Rectangle, and so 
on) and move the pointer into the bitmap grid window. Press oneof the buttonson your mouse and the appropriate action 
will take place. You can either set, clear, or invert the grid squares. Setti ng a grid square correspondsto setti ng a bit in the 
bitmap image to 1. Clearing a grid square correspondsto setti ng a bit in the bitmap image to 0. Inverting a grid square 
correspondsto changinga bit in the bitmap image from 0 to 1 or 1 to 0, dependi ngwhat its previ ous state was. Thedefault 
behavior of mouse buttons isasfollows: 
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-proportional, tproportional 

-dashes f i I ename 
-stipple f il ename 
-hi color 
-f r color 
f ilename 

basename 

bmtoa acceptsthefollowingoption: 

-chars ce 

atobmacceptsthefollowingoptions: 

-chars ce 

-name vari a b I e 

-xhot number 
-yhot number 
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MouseButtonl Set 
MouseButton2 Invert 
MouseButton3 Clear 
MouseButton4 Clear 
MouseButton5 Clear 

This default behavior can bechanged by setti ng the button function resources. H ereisan example: 

bitmap*button1Function: Set 
bitmap*button2Function: Clear 
bitmap*button3Function: Invert 
etc. 

Thebutton function appliesto ali drawingcommands, includingcopying, movingand pasting, flood filling, and setting the 
hot spot. 

DRAWINGCOMMANDS 

H ere is the list of drawing commands accessi ble through the buttons at the left side of the application's window. Some 
commandscan beaborted by pressing A inside the bitmap window, allowi ng the user to select different guidi ng pointswhere 
appli cable. 

Clear Thiscommand clearsall bits in the bitmap image. Thegrid squareswill beset to the 

background color. Pressi ngC inside the bitmap window hasthesameeffect. 

Set Thiscommand sete ali bits in the bitmap image. Thegrid squareswill beset to the 

foreground color. Pressing S inside the bitmap window hasthesameeffect. 

Invert Thiscommand inverts ali bitsin thebitmap image. Thegrid squareswill beinverted 

appropri atei y. Pressingl inside the bitmap window hasthesameeffect. 

Mark Thiscommand isusedto markan area of thegrid by dragging out a rectangular 

shape in the highlighting color. After the area ismarked, itcan beoperated on bya 
numberof commands (seeU p, Down, Left, Right, Rotate, Flip, Cut, and soon). 
Only onemarked area can bepresent at any ti me. If you atterri ptto mark another 
area, the old mark will vanish. Thesameeffect can beachieved by pressing Shift- 
M ouseButtonl and dragging out a rectangle in thegrid window. Pressing Shift- 
M ouseButton2 will mark the enti re grid area. 

Unmark Thiscommand will cause the marked areato vanish. Thesameeffect can be 

achieved by pressing Shift-M ouseButton3. 

Copy Thiscommand isused to copy an area of thegrid from one location to another. If 

there isno marked grid area displayed, Copy behavesjust likeM ark. 0 ncethereisa 
marked grid area displayed in the highlighting color, thiscommand hastwo 
alternative behaviors. If you click a mouse button inside the marked area, you will be 
ableto drag the rectangle that represents the marked areato the desi red location. 
After you release the mouse button, the area will becopied. If you click outsi de the 
marked area, Copy will assume that you wish to mark a different region of the 
bitmap image, thus itwill behavelikeM ark again. 

M ove Thiscommand isused to movean area of thegrid from one location to another. Ite 

behavior resembles the behavior of Copy comm and, except that the marked area will 
bemoved instead of copied. 

Flip H orizontally Thiscommand will flip thebitmap image with respect to thehorizontal axes. If a 

marked area of thegrid is highlighted, itwill operate only inside the marked area. 

Pressing H inside the bitmap window hasthesameeffect. 
Up Thiscommand moves the bitmap imageone pixel up. If amarked area of thegrid is 

highlighted, itwill operateonly inside the marked area. Pressing UpArrow inside the 

bitmap window hasthesameeffect. 
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Left 
Fold 
Right 
Rotate Left 
Down 

Rotate Right 
Point 

Curve 

Line 

Rectangle 

Fili ed Rectangle 
Circle 

Filled Circle 
Flood Fili 



Thiscommand will flip thebitmap imagewith respect to the verti cai axes. If a 
marked area of thegrid is highlighted, i t will operate only inside the marked area. 
PressingV insidethebitmapwindow hasthesameeffect. 
Thiscommand moves thebitmap imageone pixel to the left. If a marked area of the 
grid is highlighted, itwill operate only inside the marked area. Pressing LeftArrow 
insidethebitmapwindow hasthesameeffect. 

Thiscommand will fold thebitmap imageso that theoppositecorners become 
adjacent. Thisisuseful when creati ng bitmap imagesfortiling. Pressing F inside the 
bitmap window hasthesameeffect. 

Thiscommand moves the bitmap imageone pixel to the right. If a marked areaof 
thegrid is highlighted, itwill operate only inside the marked area. Pressing the right 
arrow insidethebitmapwindow hasthesameeffect. 

Thiscommand rotates the bitmap image 90 degreesto the left (counter clockwise.) 
If a marked area of thegrid is highlighted, itwill operate only in si de the marked 
area. Pressing L insidethebitmapwindow hasthesameeffect. 
Thiscommand moves the bitmap imageone pixel down. If a marked area of thegrid 
is highlighted, itwill operateonly inside the marked area. Pressing the down arrow 
insidethebitmapwindow hasthesameeffect. 

Thiscommand rotates the bitmap image 90 degreesto the right (clockwise.) If a 
marked area of thegrid is highlighted, itwill operateonly inside the marked area. 
P ressi ng R i nside the bitmap wi ndow has the same effect. 
Thiscommand will change the grid squaresunderneath the mouse pointer if a 
mouse button isbeing pressed down. If you drag the mouse button continuously, 
the line may not be conti nuous, dependi ng on thespeed of your system and 
frequency of mouse motion events. 

Thiscommand will change the grid squaresunderneath the mouse pointer if a 
mouse button isbeing pressed down. Ifyou drag the mouse button continuously, it 
will make sure that the line is conti nuous. If your system isslow or bitmap receives 
veryfew mouse motion events, it mightbehavequitestrangely. 
Thiscommand will change the grid squaresin a linebetween two squares. 0 nceyou 
press a mouse button in thegrid window, bitmap will highli ght the li nefrom the 
squarewhere the mouse button was i ni ti al I y pressed to the squarewhere the mouse 
pointer islocated. By releasing the mouse button, you will cause the change to take 
effect, and the highlighted linewill disappear. 

Thiscommand will change the grid squaresin a rectangle between two squares. 
0 nceyou press a mouse button in thegrid window, bitmap will highlightthe 
rectanglefrom the squarewhere the mouse button was i nitially pressed to thesquare 
where the mouse poi nter is located. By releasing the mouse button you will cause the 
change to take effect, and the highlighted rectangle will disappear. 
Thiscommand isidentical to Rectangle, except at the end the rectangle will be filled 
ratherthan outlined. 

Thiscommand will change thegrid squaresin a circle between two squares. Once 
you press a mouse button in thegrid window, bitmap will highlight the circlefrom 
the squarewhere the mouse button was initially pressed to the squarewhere the 
mouse poi nter islocated. By releasing the mouse button you will cause the change to 
take effect, and the highlighted ci relè will disappear. 

Thiscommand is identical to Circle, except at the end the ci relè will be fi lied rather 
than outlined. 

Thiscommand will flood fili theconnected area underneath the mouse pointer 
when you click on the desi red square. D iagonally adjacent squares are not considered 
to beconnected. 
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Set H ot Spot 



C lear H ot Spot 
Undo 



Thiscommand designatesonesquarein thegrid as the hot spot if this bitmap image 
isto beused for defininga cursor. Pressing a mouse button in the desi red squarewill 
causeadiamond shapeto bedisplayed. 

Thiscommand removesany designated hot spot from the bitmap image. 
Thiscommand will undo thelast executed command. It hasdepth one, that is, 
pressing U ndo afterU ndo will undo itself. 



FILE MENU 

TheFilemenu commands can beaccessed by pressing the File button and selecting the appropriate menu entry, orby 
pressing the Ctrl key with another key. These commands deal with filesand global bitmap parameters, such assize, 
basename, filename, and so forth. 



N ew 



Load 



Insert 



Save 



SaveAs 



Resize 



Rescale 



Filename 



Basename 



Quit 



This command will clear the editing area and prompt for the name of the new fi le to 
beedited. It will not load in the new file. 

Thiscommand isused to load a new bitmap file into the bitmap editor. If the 
current image has not been saved, user will beasked whether to save or ignorethe 
changes. The editor can edit only one fi le at a ti me If you need interacti ve editing, 
run anumber of editorsand use the cut and paste mechanism asdescribed laterin 
this section. (See"Cut and Paste") 

Thiscommand is used to insert a bitmap file into the image béng currently edited. 
After bei ng prompted for the filmarne click inside thegrid window and drag the 
outlined rectangleto the location whereyou want to insert the new file. 
Thiscommand will save the bitmap image. It will not prompt for thefilename 
unlessit issaid to be<none>. If you leavethefilenameundesignated or-, the output 
will bepiped to stdout. 

Thiscommand will save the bitmap image after promptingfor a new filename. It 
should beused if you wantto change the filename. 

Thiscommand isused to resize the editing area to the new number of pixels The 
size should beentered in the widthl height format. The information in theimage 
bei ng edited will not belost unlessthenew sizeissmaller that the current image size. 
T he editor was not designed to edit huge fi lea 

Thiscommand isused to rescale the editing area to the new width and height. The 
size should beentered in the widthl height format. It will not do anti aliasi ng and 
information will belost if you rescale to the smaller sizes. Feel freeto add you own 
algorithmsfor better rescaling. 

Thiscommand isused to change the fi lenamewithout changing the basename nor 
savi ng the fi le. If you speci fy - for a filename, the output will bepiped to stdout. 
Thiscommand isused to change the basename, if a different one from the specified 
fi lename is desi red. 

Thiscommand will termi nate the bitmap application. If the fi le was not saved, user 
will be prompted and asked whether to save the image or not. Quit ispreferred over 
killingtheprocess. 



EDIT MENU 

The Edit menu commands can beaccessed by pressing the Edit button and selecting the appropriate menu entry, or by 
pressing M età key with another key. These commands deal with editing faci lities such asgrid, axes, zoomi ng, cut and paste, 
and so on. 

Image Thiscommand will display the image bei ng edited and its inverse in itsactual size in 

a separate window. The window can bemoved away to continue with editing. 
Pressing the left mouse button in theimage window will causeitto disappearfrom 
thescreen. 
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Grid 

Dashed 
Axes 

Stippled 
Proporti onal 
Zoom 



Cut 

Copy 

Paste 



Thiscommand controis the grid in the editing area. If the grid spaci ng isbelow the 
valuespecified by gridToierance resource (8 by default), thegrid will beautomati- 
cally turned off. Itcan beenforced by explicitly activating thiscommand. 
Thiscommand controis the stipplefor drawing thegrid lines. Thestipplespecified 
by dashes resource can be turned on or off by activating thiscommand. 
This command controis the highlighting of the mai n axes of the i mage bei ng edited. 
Theactual lines are not part of the i mage. They are provi ded to aid user when 
constructingsym metri cai images, orwhenever havingthemain axeshighlighted 
helps your editing. 

Thiscommand controis the stippling of thehighlighted areasof thebitmap image. 
Thestipplespecified by stipple resource can be turned on or off by activating this 
command. 

Thiscommand controis the proportional mode If theproportional modeison, 
width and heightof ali image squares are forced to beequal, regardlessof the 
proporti onsof thebitmap window. 

Thiscommand controis the zoom mode. If there isa marked area of the image 
already displayed, bitmap will automatically zoom into it. Otherwise, the user will 
haveto highlightan areato be edited in thezoom mode and bitmap will automati- 
cally switch into it. You can use ali the editing commands and other Utilities in the 
zoom mode. W hen you zoom out, undo command will undo thewholezoom 
session. 

T his commands cuts the contentsof thehighlighted image area into the internai cut 
and paste buffer. 

Thiscommand copies the contentsof thehighlighted image area into the internai 
cut and paste buffer. 

Thiscommand will check if there are any other bitmap applicati onswith a 
highlighted image area, or if there issomething in the internai cut and paste buffer 
and copy itto the i mage. To place the copi ed image, click in the editing window and 
drag theoutlined image to the position whereyou wantto placei, and then release 
thebutton. 



CUT AND PASTE 

Bitmap supportstwo cut and paste mechanisms; the internai cut and paste and theglobal X selection cut and paste. The 
internai cut and paste isused when executing copy and movedrawing commands and also cut and copy commands from the 
Edit menu. Theglobal X selection cut and paste isused whenever there isa highlighted area of a bitmap image displayed 
anywhereon thescreen. To copy a part of image from another bitmap editor, simply highlight the desi red area by using the 
M ark command or pressing the shift key and dragging the area with theleft mouse button. When theselected area becomes 
highlighted, any other applications (such asxterm) that useprimary selection will discard their selection valuesand 
unhighlight the appropriate information. N ow, use the Paste command from the Edit menu or control mouse button to 
copy theselected part of image into another (or thesame) bitmap application. If you attempt to do thiswithout a visible 
highlighted image area, thebitmap will fall back to the internai cut and paste buffer and paste whatever wasstored there at 
the moment. 

WIDGETS 

Following isthewidget structureof thebitmap application. The widget class nameisgiven first, followed by thewidget 
instancename. Ali widgetsexcept thebitmap widget are from the standard Athena widget set. 

Bitmap bitmap 
TransientShell image 
Box box 

Label normallmage 
Label invertedlmage 
TransientShell input 
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Dialog dialog 
ComniancI okay 
Comniand cancel 
TransientShell error 
Dialog dialog 
Command abort 
Command retry 
TransientShell qsave 
Dialog dialog 
Command yes 
Command no 
Command cancel 
Paned parent 
Form formy 

MenuButton fileButton 
SimpleMenu fileMenu 
SmeBSB new 
SmeBSB load 
SmeBSB insert 
SmeBSB save 
SmeBSB saveAs 
SmeBSB resize 
SmeBSB rescale 
SmeBSB filename 
SmeBSB basename 
SmeLine line 
SmeBSB quit 
MenuButton editButton 
SimpleMenu editMenu 
SmeBSB image 
SmeBSB grid 
SmeBSB dashed 
SmeBSB axes 
SmeBSB stippled 
SmeBSB proportional 
SmeBSB zoom 
SmeLine line 
SmeBSB cut 
SmeBSB copy 
SmeBSB paste 
Label status 
Pane pane 
Bitmap bitmap 
Form form 
Command clear 
Command set 
Command invert 
Toggle mark 
Command unmark 
Toggle copy 
Toggle move 
Command flipHoriz 
Command up 
Command flipVert 
Command left 
Command fold 
Command right 
Command rotateLeft 
Command down 
Command rotateRight 
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Toggle point 
Toggle curve 
Toggle line 
Toggle rectangle 
Toggle f illedRectangle 
Toggle circle 
Toggle f illedCircle 
Toggle floodFill 
Toggle setHotSpot 
Command clearHotSpot 
Command undo 



If you would like bitmap to beviewablein color, include the foli ovvi ng in the#ifdef color section of the file you read with 

xrdb: 

*customization: -color 

Thiswill cause bitmap to pick up thecolorsin the app-defaults color customization file 

<XRoot>/lib/X1 1 /app-defaults/Bitmap-color 

where <xRoot> refersto theroot of theXll instali tree. 



Bitmap widgetis a standalonewidgetfor editing raster images. It isnot designed to edit largeimages, although it may be 
used in that purposeaswell. It can befreely incorporated with other appi ications and used as a standard editing tool. The 
followi ng are the resources provided by the bitmap widget: 



COLORS 



BITMAP WIDGET 



Headerfile Bitmap. n 



Class bitmapWidgetClass 



C lass N ame Bitmap 
Superclass Bitmap 



Ali theSimpleW idget resources plus... 



N ame 



Class 



Type 



Default Value 



foreground 
highlight 
framing 
gridTolerance 



Foreground 

Highlight 

Framing 

GridTolerance 

Size 

Dashed 

Grid 

Stippled 

Proporti onal 

Axes 

SquareWidth 
SquareH eight 
M argin 
XHot 
YHot 

ButtonlFunction 



Pixel 
Pixel 
Pixel 

D imension 

String 

Boolean 

Boolean 

Boolean 

Boolean 

Boolean 

D imension 

D imension 

D imension 

Position 

Position 

D rawingFunction 



XtD efaultForeground 
XtD efaultForeground 
XtD efaultForeground 
8 

32x32 

True 

True 

True 

True 

False 

16 

16 

16 

NotSet(-l) 
NotSet(-l) 
Set 



size 



dashed 
grid 

stippled 
proporti onal 



axes 



squareWidth 
squareH eight 



m argin 
xH ot 
yH ot 



buttonlFunction 



brushtopbm 



I ame 



Clas 



Type 



D efault Value 



button2Function 

button3Function 

button4Function 

button5Function 

filename 

basename 



Button2Function 

Button3Function 

Button4Function 

Button5Function 

Filename 

Basename 



AUTHOR 

Davor M atic (M IT X Consortium) 



D rawingFunction 
D rawingFunction 
D rawingFunction 
D rawingFunction 
String 
String 



Invert 

Clear 

Invert 

Invert 

N one("" 

None("" 
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bmptoppm 

bmptoppm— Convert a BM P fileinto a portablepixmap 
SYNOPSIS 

bmptoppm [bmpfile] 

D ESC RIPTIO N 

bmptoppm readsaM icrosoftW indowsor OS/2 BM P fileasinput and produces a portable pixmap as output. 
SEEALSO 

ppmtobmp(l), ppm(5) 

AUTHOR 

Copyright © 1992 by D avid W . Sanderson 

26 0ctober 1992 

brushtopbm 

brushtopbm— C onvert a doodle brush file into a portable bitmap 
SYNOPSIS 

brushtopbm [brushfiie] 

D ESC RIFIO N 

brushtopbm reads a Xerox doodle brush fi le as input and produces a portable bitmap as output. 
N otethat there iscurrently no pbmtobrush tool. 

SEEALSO 

pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 



28 August 1988 
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cai 

cai— D isplaysa calendar 
SYNOPSIS 

cai [-jy] [mont h [ y e a r ]] 

D ESC RIPTIO N 

cai displays a simple calendar. If argumentsarenot specified, thecurrent month isdisplayed. The opti ons are asfollows: 
-j D isplayjulian dates(days one-based, numberedfromjanuaryl) 

-y D isplay a calendar for the current year 

A single parameter specifies the year (1-9999) to bedisplayed; note the year must be fui ly specified: 

cai 89 

will not display a calendar for 1989. Two parameters denote the month (1-12) and year. If no parameters are specified, the 
current month's calendar isdisplayed. 

A year startsonjan 1. 

TheGregorian Reformation isassumed to haveoccurred in 1752 on the 3rd of September. By thistime, most countries had 
recognized the reformation (although a few di d not recognizeit until theearly 1900s.) Ten daysfollowing that datewere 
eliminated by the reformation, so the calendar for that month isabitunusual. 

HI STORY 

A cai command appeared in version 6 AT&T UNIX 

6 Junel993 

cat 

cat— Concatenate files and print on the standard output 
SYNOPSIS 

cat [-benstuvAET] [-number] [ -number-nonblank] [ -squeeze-blank] 
[ -show-nonprinting] [ — show-ends] [-show-tabs] [-show-ali] 
[-help] [-version] [file...] 

DESCRIPTION 

Thismanual page documents the GN U version of cat. cat writesthecontentsof each given file, or the standard input if 
none are given orwhen afilenamed - isgiven, to thestandard output. 

OPTIONS 

-b, -number-nonbiank N umber ali nonblank output lines, starti ng with 1. 

-e Equivalentto -vE. 

-n, -number N umber ali output lines, starting with 1. 

-s, -squeeze-biank R epl ace multiple adj acent blank lines with a single blank line. 

-t Equivalentto -vt. 

-u Ignored; for U N IX compati bility. 



-v, —show-nonprinting 

-A, —show -ali 
-E, —show-ends 
-T, -show-tabs 
— help 



chattr 



D i splay control characters except for lfd and tab usi ng " notation and precede characters that 

have the high bit set with m-. 

Equivalentto -vet. 

D i splay a$ after the end of each line 

D i splay tab characters as 'i. 

Print ausagemessageand exit with a nonzero status. 

Print version informati on on standard output then exit. 

GNU Text U tilities 



chattr 

chattr— Change file attributeson a Linux second extended file system 
SYNOPSIS 

chattr [ -RV ][-v version ] [ mode ] files... 

D ESC RIPTIO N 

chattr changes the files attributeson an second extended fi le system. The format of a symbol ic modeis + -=[sacdisu]. 

Theoperator + causestheselected attri butes to beadded to the exi sti ng attri butes of the files; - causesthem to beremoved; 
and = causesthem to betheonly attri butes that the files have. The letters sacdisu select thenew attri butes for the files: 
synchronousupdates(s), append only (a), compressed (%), immutable(i), nodump (d), securedeletion (s), and undeletable 



OPTIONS 



Recursively change attri butes of di recto ri es and their contents. 
Verbosely describechanged attri butes. 
Set thefile's version. 



ATTRI BUTES 

A file with the a attri bute set can only beopen in append mode for writing. 

A fi le with the c attri bute set isautomatically compressed on the disk by the kernel. A read from thisfilereturns 
uncompressed data. A writeto thisfilecompressesdata before stori ngthem on thedisk. 

A fi le with the d attri bute set isnot candidate for backup when the dump (8) program isrun. 

A fi le with the i attri bute cannot bemodified: it cannot bedeleted or renamed, no link can becreated to thisfileand no data 
can bewritten to the fi le. Only the superuser can set or clear this attri bute. 

When afilewith thes attri bute set isdeleted, itsblocksarezeroed and written backto thedisk. 

When afilewith theu attri bute set ismodified, the changes are written synchronously on thedisk; thisis equivalentto the 
syn 1 mount option appi i ed to asubset of the files. 

When afilewith theu attri bute set isdeleted, its contents issaved. This allows the user to ask for itsundeletion. 
AUTHOR 

chattr has been written by Remy Card, <cardiamasi.ibp.fr>, thedeveloper and maintainer of theext2 fs. 

BUG SANO LIMITANO NS 

As of ext2 f s 0.5a, the c and u attri butes are not honored by the kernel code. 
Theseattributeswill beimplemented in afutureext2 ts version. 
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AVAILABILITY 

chattr isavailablefor anonymOUSftp from ftp.ibp.fr and tsx-11 .mit.edu in /pub/linux/packages/ext2fs. 

SEEALSO 

lsattr(l) 

Version 0.5b, Novemberl994 



chfn 

chfn— Changeyour finger information 
SYNOPSIS 



chfn [ — -f fui I - n a me ][-o office][-p office-phone ] [ -h home- p ho ne ] [ -u ] [ 
[username ] 



DESCRIVO N 

chfn isused to changeyour finger information. Thisinformation isstored in the/etc/passwd file, and isdisplayed by the 
finger program. The Linux finger command will display four pieces of information that can bechanged by chfn: your real 
name, your work room and phone, and your home phone. 

COMMAND UNE 

Any of the four pieces of information can bespecified on the command line If no information isgiven on the command 
line, chfn enters interactive mode 

INTERACTIVE MODE 

In interactive mode, chfn will promptfor each field. At a prompt, you can enterthenew information, or just press return to 
leavethefield unchanged. E nter the keyword none to makethefield blank. 



OPTIONS 




-f, — full-name 


Specify your real name. 


-o, -office 


Specify your office room number. 


-p, -office-phone 


Specify your office phone number. 


-h, — home-phone 


Specify your home phone number. 


-u, -help 


Printausagemessageand exit. 


-v, —version 


Print version information and exit. 


SEEALSO 





finger(l), passwd(5) 

AUTHOR 

Salvato re Valente (<svalente?mit.edu>) 



chfn, OctoberB 1994 
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chgrp— C hange the group ownershi p of files 
SYNOPSIS 

chgrp [-Rcfv] [—recursive] [-changes] [-silent] [— quiet] [—verbose] [— help] 
[ -version] group file... 

DESCRIVO N 

Thismanual page documents the GN U version of chgrp. chgrp changes the group ownershi p of each given fileto thenamed 
group, which can beeither a group nameor a numeri c group ID . 

OPTIONS 

-e -changes Verbosely describeonly fi les w h ose ownershi p actually changes. 

-f, -siient, -quiet D o not print errar messages about files whose ownership cannot be changed. 

-v, -verbose Verbosely describe ownership changes. 

-R, -recursive Recursively change ownership of directoriesand their contents. 

-heip Printausagemessageon standard output and exitsuccessfully. 

-version Print version information on standard output, then exit successfully. 

GNU FileU tilities 



chkdupexe 

chkdupexe— Fi nd duplicate executables 



SYNOPSIS 

chkdupexe 

DESCRIPTION 

chkdupexe will scan many standard di rectories that hold executable, and report duplicates. 

AUTHOR 

N icolai Langfeldt 

BUGS 

RequiresGNU is(l). 

Search pathsthat pointto the same directory will cause many bogus duplicates to befound. You mightwantto editthe 
script to eli mi nate some pathsthat are equi vai ent on your machine. 

11 M arch 1995 



chmod 

chmod— C hange the access permissions of files 
SYNOPSIS 



chmod [-Rcfv] [—recursive] [-changes] [-silent] [—quiet] [—verbose] [-help] 
[ —version] mode file... 
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DESCRIPTION 



Thismanual page documents the GN U version of chmod. chmod changesthepermissionsof each given fileaccordingto mode, 
which can beeither asymbolic representation of changesto make, or an octal number representi ng the bit pattern forthe 
new permissions. 

Theformat of a symbolicmodeis [ugoa. ..][[+-=] [rwxxstugo. ..] . ..][,...]. M ulti pie symbolic operations can be given, 
separated by commas. 

A combination of the lettere ugoa controis which users' access to the fi le wi II bechanged: the user who ownsit (u), other users 
in thefile'sgroup (g), other users not in thefile'sgroup (o), or ali users (a). If none of these are given, theeffect isasif a were 
given, but bits that are set i n the umask are not affected. 

Theoperator + causes the permissions selected to beadded to theexisting permissions of each file ■ causesthem to be 
removed; and = causesthem to betheonly permissions that the file has. 

Theletters rwxxstugo select the new permissions forthe affected users: read (r), write(w), execute(or access for di rectories) 
(x), executeonly if the file is a directory or al ready has execute perni ission for some user (x), set user or group ID on 
execution (s), save program text on swap device (t), the permissions that the user who ownsthefilecurrently has for it (u), 
the permissions that other users in thefile'sgroup havefor it (g), and the permissions that other users not in thefile's group 
haveforit(o). 

A numeric modeisfrom oneto four octal di gits (0-7), derived by adding up the bits with values4, 2, and 1. Any omitted 
digitsareassumed to beleadingzeros. The first digit selects theset user I D (4) and set group ID (2) and save text image(i) 
attributes. Thesecond digit selectspermissionsfor theuser who ownsthefile: read (4), write(2), and execute(i); thethird 
selects permissions for other users in thefile'sgroup, with thesamevalues; and thefourth for other users not in thefile's 
group, with thesamevalues 

chmod never changesthepermissionsof symbolic links: the chmod system cali cannot changetheir permissions. Thisis not a 
problem si nce the permissions of symbolic links are never used. H owever, for each symbolic link listed on thecommand line, 
chmod changesthepermissionsof thepointed-to file. In contrast, chmod ignores symbolic links encountered during recursive 
directory traversals. 



0PTI0NS 



-v, —verbose 



-c, -changes 

-f, — silent, — quiet 



Verbosely describe only files whose permissions actually change. 

D 0 not print errar messages about files whose permissions cannot be changed. 

V erbosel y descri be eh anged perm i ssi 0 n s. 



-R, - 



— help 



recursive 



Recursively change permissions of di rectories and their contents. 
Printausagemessageon standard output and exit successfully. 



— version 



Print version informati on on standard output, then exit successfully. 
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chown— C hange the user and group ownership of files 



SYNOPSIS 



chown [-Rcfv] [—recursive] [—changes] [—help] [—version] [—silent] [ — quiet] 
[-verbose] [u s er ] [ : . ] [g r ou p ] file... 



chsh ^ 

D ESC RIPTIO N 

Thismanual page documents the GN U version of chown. chown changes the user and/or group ownership of each given file, 
accordi ngto its first nonoption argument, which isinterpreted asfollows. If only ausername(or numeric user ID ) is given, 
that user ismadetheowner of each given file, and thefiles' group is not changed. If theusernameisfollowed by a colon or 
dot and a group name(or numeric group ID ), with no spaces between them, the group ownership of the fi lesis changed as 
well. If a colon or dot but no group namefollowstheusername that user ismadetheowner of thefiles and the group of the 
fi lesis changed to that user'slogin group. If the colon or dot and group are given, but theusernameisomitted, only the 
group of thefiles ischanged; in thiscase, chown performsthesamefunction aschgrp. 

OPTIONS 

-c, —changes 
-f, -silent, — quiet 
-v, —verbose 
-R, —recursive 

— help 

— version 

GNU FileU tilities 



Verboselydescribeonlyfileswhoseown ersh i p actual I y eh an ges. 

Do not print errar messages about fileswhose ownership cannot be changed. 

V erbosel y descri be own ersh i p eh anges. 

Recursively change ownership of directoriesand their contenta 

Printausagemessageon standard output and exit successfully. 

Print version information on standard output then exit successfully. 



chsh 

chsn— Change yourlogin shell 
SYNOPSIS 

chsh [ -s shell ] [ -1 ] [ -u ] [ -v ] [ u s e r n a me ] 

DESCRIPTION 

chsh isused to change your login shell. If a shell is not given on thecommand line, chsh promptsfor one. 
VAUD SHELLS 

chsh will accept thefull pathnameof any executablefileon the system. However, itwill issue a warning if the shell isnot 
listed in the /etc/sheiis file. 

OPTIONS 

-s, -sheii Specify your login shell. 

-ì, -ìist-sheiis Pri nt the list of shells listed in /etc/sheiis and exit. 

-u, -heip Printausagemessageand exit. 

-v, -version Print version information and exit. 

SEEALSO 

login(l), passwd(5), shells(5) 

AUTHOR 

Sai vatO re V alente (<svalente?mit . edu>) 

chsh, 13 October 1994 
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ci 

ci— Check in RCS revisions 
SYNOPSIS 

ci [options] file ... 

D ESC RIPTIO N 

ci stores new revisions into RCS files. Each pattinarne matching an RCS suffix istaken to bean RCS file Ali othersare 
assumed to be working files contai ning new revisions. ci deposi ts the contentsof each working fi le into thecorresponding 
RCSfile. If only a working fi lei sgiven, ci triesto find thecorresponding RCS file in an RCS subdirectory and then in the 
working fi le's directory. (For moredetails, see "File N ami ng," later in thismanual page.) 

For ci to work, the caller's login must beon the access list, uni ess the access list isempty or the Caller isthesuperuser or the 
owner of the file. To append a new revision to an existing branch, thetip revision on that branch must belocked by the 
Caller. Otherwise, only a new branch can be createci. This restriction isnot enforced for the owner of the file if non-strict 
locking isused; seercs(l). A lock held by someone else can bebroken with thercscommand. 

U nlessthe-f option isgiven, ci checkswhether the revision to bedeposited differsfrom the precedi ngone If not, instead of 
creati ng a new revision ci revertsto the precedi ngone. To revert, ordinary ci removes the working fi le and any lock; ci -I 
keepsand ci -u removes any lock, and then they both generate a new working fi le much asif co -1 or co -u had been appi i ed 
to the precedi ng revision. When reverting, any-n and -s options apply to the precedi ng revision. 

For each revision deposited, ci promptsfor a log message. The log messageshould summarizethechangeand must be 
termi nated by end-of-fileor by a line contami ng . by itself. If several files are checked in, ci askswhether to reusethe 
previ ous log message. If the standard input is not a terminal, ci suppressestheprompt and usesthesamelog message for ali 
files. (Seealso -m.) 

If the RCS file does not exist, ci createsit and deposits the contentsof the working file as the initial revision (default 
number: 1.1). Theaccess list isinitialized to empty. Instead of the log message, ci requests descri ptive text (See-t.) 

Thenumber rev of the deposited revision can begiven by any of the options -f, -i, -1, -j, -k, -1, -m, -q, -r, or -u. revean be 
symbolic, numeri c, or mixed. Symbolic namesin rev must already be defined; see the -n and -n opti ons for assi gning names 
during checkin. If rev is$, ci determi nes the revision number from keyword valuesin the working fi le. 

If rev beginswith a period, then the default branch (normally thetrunk) isprepended to it. If rev is a branch number 
followed by a period, then the latest revision on that branch isused. 

If rev is a revision number, it must behigher than the latest oneon the branch to which rev belongs, or must start a new 
branch. 

If rev is a branch ratherthan a revision number, the new revision isappended to that branch. The level number isobtained 
by incrementi ng thetip revision number of that branch. If rev indicatesa nonexistent branch, that branch iscreated with the 
initial revision numbered rev.1. 

If rev isomitted, ci triesto derive the new revision number from the caller's last lock. If the Caller haslocked thetip revision 
of a branch, the new revision isappended to that branch. The new revision number isobtained by incrementi ng thetip 
revision number. If the Caller locked anontip revision, a new branch isstarted at that revision by incrementi ng the highest 
branch number atthat revision. The default initial branch and level numbersarei. 

If rev isomitted and the Caller hasno lock, but ownsthefileand locking is not set to stri et, then the revision isappended to 
the default branch. (N ormai ly thetrunk; see the -b option of rcs(l).) 

Exception: On thetrunk, revisions can beappended to the end, but not inserted. 



ci [T| 

OPTIONS 

-rr ev Check in revision r e v . 

-r The bare -r option (without any revision) hasan unusual meaning in ci. With other RCS 

commands, a bare -r option specifiesthemost recent revision on the default branch, but with ci, a 
bare -r option reestablishes the default behavior of releasing a lock and removi ng the working fi le, 
and isused to override any default -1 or -u optionsestablished by shell aliasesor scripts. 

-i[r ev ] Works li ke -r, except it performsan additional co -ìfor the deposi ted revision. Thus, the 

deposi ted revision isimmediately checked out again and locked. Thisisuseful for savi ng a revision 
although onewantsto continue editing it after thecheckin. 

-u[rev] Works li ke -1, except thatthedeposited revision isnot locked. Thisletsoneread the working fi le 

immediately after checkin. 

The-i, bare -r, and -u optionsaremutually exclusiveand si lently override each other. Forexample, ci -u -r isequivalent 
to ci -r because bare -r overrides -u. 

-f [r ev ] Forcesadeposit; thenew revision isdeposited even it isnot different from the preceding one. 

-k[r ev ] Searches the working fi le for keyword valuesto determine its revision number, creation date, state, 

and author— see co(l)— and assignsthese valuesto thedeposited revision, rather than computing 
them locally. It also generates a default login messagenoting thelogin of the Caller and the actual 
checkin date. T hi s option isuseful for software distri bution. A revision that issentto several sites 
should be checked in with the-k option atthese sites to preserve the originai number, date author, 
and state. T he extracted keyword valuesand the default log messagecan beoverridden with the 
options-d, -m, -s, -w, and any option that carries a revision number. 

-q [ r e v ] Quiet mode; di agnostic output isnot printed. A revision that isnot different from the preceding 

oneisnotdeposited, unless-f isgiven. 

■ i[rev] Initial checkin; report an errar if the RCS fi le al ready exists. Thisavoidsraceconditionsin certain 

applications. 

- j [r ev ] Just check in and do not initialize; report an errar if the RCS file doesnotalready exist. 

-i[r ev ] Interactive mode; the user is prompted and questi oned even if the standard input isnot a terminal. 

-d [d a t e ] U ses date for the checkin date and time. Thedate isspecified in free format asexplai ned in co(l). 

Thisisuseful for lying about the checkin date, and for-k if no date is available. If dateisempty, 

theworking file's timeof last modification isused. 
-M[rev] Set the modification timeon any new working fileto be the date of the retri eved revision. For 

example, ci -d -m -u f does not alter f's modification time, even iff'scontents change due to 

keyword substitution. U sethisoption with care; it can confuse make(l). 
-mmsg U ses the stri ng ms g asthelogmessageforall revi si ons checked in. By convention, log messages that 

start with # arecommentsand areignored by programs likeGN U emacs'svc package. Also, log 

messages that start with ciumpname (followed by whitespace) aremeantto beclumped together if 

possi ble, even if they areassociated with different fi les; the ciumpname label isused only for 

dumping, and isnot considered to bepart ofthelog message itsdf. 
-nname Assigns the symbol ic nameto the number of thechecked-in revision, ci printsan errar message if 

that name is al ready assigned to another number. 
-Nname Sameas-n, exceptthat it overrides a previousassignment of name. 

-sstate Sets the state of thechecked-in revision to theidentifier state. The default state isExp. 

-tf i i e W ri tes d escri pti ve text from thecontentsof thenamed fileinto the RCS file, deleti ng the existing 

text. Thefilecannot begin with -. 
-t-st ri ng W rite descri pti ve text from the stri ng into the RCS fi le, deleti ng the existing text. 

T he -t option, in both itsforms, haseffect only during an initial checkin; it issi lently ignored otherwise. 



D uri ng the initial checkin, if -t isnot given, ci obtains the text from standard input, termi nated by end-of-fileor by a line 
containi ng a dot ( .) by itself. The user is prompted for the text if interaction is possi ble; see-i. 
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For backwards compatibility with older versionsof RCS, abare-t option isignored. 

-t Set the RC S file's modificati on ti me to the new revision 'stime if theformer precedes the I after and 

there isa new revision; preserve the RCS fi le's modificati on timeotherwise. If you havelocked a 
revision, ci usually updates the RCS file's modification timeto thecurrent ti me, becausethelock is 
stored in the RCS file and removingthelock requires changing the RCS file Thiscan create an 
RCSfilenewer than theworkingfilein oneof two ways: first, ci -m can create a working fi le with 
a date before thecurrent ti me; second, when reverting to the previous revision the RCS fi le can 
changewhiletheworkingfileremainsunchanged. Thesetwo casescan cause excessive 
recompilation caused by amake(l) dependency of the working file on the RCS file The -t option 
inhibitsthis recompilation by lyingabout the RCS fi le's date. U se this option with care it can 
suppress recompilation even when acheckin of oneworkingfileshould affect another working file 
associated with thesameRCSfile. For example, suppose the RCS fi le's ti me is 01:00, the(changed) 
worki ng fi le's ti me is 02:00, some other copy of the worki ng fi le has a ti me of 03:00, and the 
currenttimeis04:00.Then ci-d-T sets the RCS file's timeto 02:00 instead oftheusual 04:00; 
thiscausesmake(l) to think (incorrectly) that the other copy isnewer than the RCS file. 

-wi o g i n Usesiogin for the author field of the deposi ted revision. U seful for lyingabout the author, and for 

-k if no author isavailable. 

-v Print RCS's version number. 

-vn Emulate RCS version n. Seeco(l) fordetails. 

-xsuf f i xes Specifies the suffixes for RCSfiles. A nonempty suffix matchesany pathnameending in thesuffix. 

An empty suffix matchesany pathnameof theform Rcs/path or pathi/Rcs/path2. The-x option 
can specify a list of suffixes separated by / . For example, -x,v/ specifies two suffixes: ,v and the 
empty suffix. If two or more suffixes are specified, they are tried in orderwhen lookingfor an RCS 
file; the first onethat worksisused for that fi le. If no RCSfileisfound but an RCS file can be 
created, the suffixes are tri ed in order to determi ne the new RCS file's name. The default for 
suffixes is i n stai I ati o n - d epen den t; normally it is , v/ for hosts like UNIX that permit commas in 
filenames, and is empty (that is, just the empty suffix) for other hosts. 

-zzone Specifies the date output format in keyword substitution, and specif ies the default ti me zonefor 

date in the-ddate option. The zone should be empty, a numeric UTC offset, or the special stri ng 
lt for locai ti me. The default isan empty zone, which uses the traditi onal RCS format of UTC 
without any ti me-zone indication and with slashes separati ng the partsof the date otherwise, times 
are output in ISO 8601 format with timezone indication. For example, if locai time isj anuary 11, 
1990, 8 p.m. Pacific Standard Time, eight hourswest of UTC, then the ti me is output asfollows: 



O pti on 


TimeOutput 




-z 


1990/01/12 04 


00:00 (default) 


-zLT 


1990-01 -11 20 


00:00-08 


-z+05:30 


1990-01 -12 09 


30:00+05:30 



The-z option does not affect dates stored in RCSfiles, which arealwaysUTC. 

FILE NAMING 

Pairsof RCS fi Ies and working fi Ies can be specified in threeways. (Seealso "Examples," next.) 

1. Both the RCS file and the working file are given. The RCS pathnameisof theform patm/workfiiex and the working 
pathnameisof theform path2/workme wherepatm/ and path2/ are (possi bly different or empty) paths, workme isa 
filmarne, and x isan RCS suffix. If x isempty, patm/ must start with rcs/ or must contain /rcs/. 

2. Only the RCS file is given. Then the working fi le is created in thecurrent directory and itsnameisderived from the 
name of the RC S file by removing patm / and the suffix x. 



- [T| 

3. 0 nly the working file is given. T hen ci considerseach RCS suffixX in turn, lookingfor an RC S file of the forni path2/ 
Rcs/workfiiex or (if the former isnotfound and x isnonempty) path2/workmex. 

If the RCS file isspecified without a path in oneof the first two precedi ng scenari os, ci looksfor the RCS file first in the 
directory ./Rcsandthen in the current directory. 

ci reportsan errar if an atterri pt to open an RCS file failsfor an unusual reason, even if the RCS fi le's pattinarne is just one 
of several possi bilities. For example, to suppress use of RCS commandsin a directory <j, create a regular file named d/Rcs so 
that casual attemptsto use RCS commands in d fail becaused/Rcs isnot a directory. 

EXAMPLES 

Suppose ,v isan RCS suffixand the current directory contai ns a subdirectory RCS with an RCSfileio.c,v. Then each of 
thefollowing commands checks in acopyof io.c into rcs/ìo.c,v asthelatest revision, removingio.c: 

ci io.c; ci RCS/io.c,v; ci io.c.v; 
ci io.c RCS/io.c,v; ci io.c io.c.v; 
ci RCS/io.c,v io.c; ci io.c.v io.c; 

Suppose instead that the empty suffix isan RCS suffixand the current directory contai ns a subdirectory RCS with an RCS 
file io.c. Then each of thefollowing commands checks in anew revision: 

ci io.c; ci RCS/io.c; 
ci io.c RCS/io.c; 
ci RCS/io.c io.c; 

FILEMODES 

An RCSfilecreated by ci inheritstheread and executepermissionsfrom the working file. If the RCS file exists al ready, ci 
preservesitsread and execute perni issions. ci alwaysturnsoff ali write permissionsof RCSfiles. 

FILES 

Temporary filesarecreated in the directory contai ni ng the working fi le, and also in thetemporary directory. (See tmpdir 
under "Environment") A semaphore fi le or filesarecreated in the directory containing the RCS file. With anonempty 
suffix, the semaphore names begin with the first character of the suffix; therefore, do not specify an suffix whose first 
character could bethat of a working filmarne With an empty suffix, the semaphore names end with an underscore(_), so 
workingfilenamesshould not end in_. ci never changesan RCS orworkingfile. Normally, ci unlinksthefileand createsa 
new one; but instead of breaking achain of oneor more symbol ic linksto an RCS file, it uni inks the desti nation fi le instead. 
Therefore, ci breaksany hard or symbolic linksto any working file it changes; and hard linksto R C S f i I es are i neff ecti ve, but 
symbolic linksto RCSfiles are preserved. 

Theeffectiveuser must beableto search and write the directory containing the RCS file. N ormally, thereal user must be 
ableto read the RCS and working fi les and to search and write the directory containing the working file; however, some 
older hostscannoteasily switch between real and effectiveusers, soonthesehoststheeffectiveuserisused forali accesses. 
Theeffectiveuser is the sameas the real user unlessyour copiesof ci and co havesetuid pri vi leges. These privi leges yield 
extra security if theeffectiveuser owns ali RCSfiles and directories, and if only theeffectiveuser can write RCS di rectories. 

Userscan control access to RCSfiles by setti ng the permissionsof the directory containing the fi les; only users with write 
access to the directory can use RCS commands to changeits RCSfiles. For example, in hoststhat allow a user to belong to 
several groups, one can makea group's RCS directories writableto that group only. Thisapproach suffices for informai 
projects, but it meansthat any group member can arbitrari lychange the group's RCS fi les, and can even remove them 
entirely. Hence, more formai projects sometimes distinguish between an RCS administrator, whocan changethe RCS files 
atwill, and other project members, who can check in new revisions but cannot otherwise changethe RCS fi les. 

setuidUSE 

To prevent anybody but their RCS administrator from deleti ng revisions, a set of userscan employ setuid pri vi leges as 
follows: 
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■ C heck that the host supports RC S setuid use. C onsult a trustworthy expert if there are any doubts. It is best if the 
setuid system calls works as described in POSIX 1003. la D raft 5, becauseRCS can switch back and forth easily 
between real and effectiveusers, even if thereal user isroot. If not, thesecond best isif the setuid system cali supports 
saved setuid (the{_posix_sAVED_iDS} behavior of POSIX 1003.1-1990); thisfailsonly if thereal or effectiveuser isroot. 
If RC S detects any fai Iure in setuid, it quits immediately. 

■ Chooseauser A to serve as RC S administrator for the set of users. Only A can invokethercscommand on theusers' 
RCSfiles. A should not berootoranyotheruserwith special powers. M utually suspi ci oussetsof users should use 
different administrators. 

■ C hoose a pathname B to be a directory of files to be executed by the users. 

■ H ave A set up B to contai n copiesof ci and co that are setuid to A by copyingthecommandsfrom their standard 
installation directory D asfollows: 

mkdir B cp D/c[io] B chmod go-w,u+s B/c[io] 

■ H ave each user prepend B to his/her path asfollows: 

PATH=B:$PATH; export PATH # ordinary shell 
set path=(B $path) # C shell 

■ H ave A create each RCS directory R with write access only to A asfollows: 

mkdir R chmod go-w R 

■ If you want to let only certain users read the RCS files, put the users into agroup G, and haveA further protecttheRCS 
directory asfollows: 

chgrp G Rchmod g-w,o-rwx R 

■ HaveA copy old RC S files (if any) into R, to ensurethat A ownsthem. 

■ An RCSfile's access list limitswho can check in and lock revi si ons. The default access list isempty, which grants 
checkin access to anyonewho can read the RCS file. If you want limit checkin access, haveA invokercs -a on the file; 
seercs(l). In parti cular, rcs -e -aA limits access to just A. 

■ H ave A initializeany new RCS files with rcs -i beforeinitial checkin, addi ng the -a option if you want to limit checkin 
access. 

■ Gi ve setuid privi leges only to ci, co, and rcsciean; do not givethem to rcs orto any other command. 

■ Do not use other setuid commands to invoke RCS commands; setuid istrickier than you think! 

ENVIR0NMENT 

rcsinit Opti ons prepended to theargument list, separated by spaces. A backslash escapesspaceswithin an option. 

The rcsinit options are prepended to theargument listsof most RCS commands. Useful rcsinit opti ons 
include -q, -v, -x, and -z. 

tmpdir N ameof the temporary directory. If not set, theenvironment vari ablesTMP andTEMPsoareinspected 

instead and the first valuefound istaken; if noneof them are set, a host-dependent default isused, 
typically /tmp. 

DIAGN0STICS 

For each revision, ci printstheRCSfile, the working file, and thenumber of both the deposi ted and the precedi ng revision. 
T he exit status is zero if and only if ali operationsweresuccessful. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual page revision: 5.17; Rei ease date 16 J une 1995 

Copyright © 1982, 1988, 1989 Walter F. Tichy 

Copyright © 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert 



ci dentei 



SEEALSO 

co(l), emacs(l), ident(l), make(l), rcs(l), rcsclean(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), setuid(2), rcsfile(5) 

Walter F. Tichy, "RCS-A System forVersion Control," Software P radi ce & Experiencel5, 7 (July 1985), 637-654. 

GNU, 16 Junel995 

cidentd 

cidentd— identd Server 

SYNOPSIS 

cidentd [-usqvnah] [-f file] [-1 file] [-t seconds] 

DESCRIVO N 

cidentd givesauthentication information. 

cidentd isan RFC 1314- and 931-compliant identd daemon. It acceptsconnectionson a port (113 default) and answers 
queries for port owner of a connection, command; 

cidentd normally terminates when the remote command does. Theoptionsareasfollows: 

-u Turnson theuseof the .autmie filein theuser'shomedirectoryto gi ve the requesti ng system whatever 

information the user provi des. This fi le isoverri dden by the - a option and the system fi le the format isas 
follows: 

mynameis name -to - be -given # give this userid 

hideme # hide user id 

host-ip name -to - be -given # userid for them 

host-ip no-info # hide you to them 

host-ip can bean ip in dot notati on or a name. T he fi le is set so that whatever comes last iswhat they get. 

-s Closes the connection after a single query. 

-q Quits the daemon after 1 connection (default in l.Ob). 

-v Turnson verbose loggingto the syslogs. 

-n M akescident act li ke the old school identd with nothing special. 

-a Enablesthe /etc/cident.users fi le for options, which overrides the user filesif -u isspecified. Theformat 

isas follows: 

username name-to-send # send this for username 

username # must send there username 

ali name-to-send # send for every query 

ali no-info # send nothing every query 

host-ip name-to-send # send to that host 

host-ip no-info # send nothing to them 

host-ip can bean ip in dot notati on or a name. T he fi le is set so that whatever comes last iswhat they get. 
-h D isplaysthehelp listto thescreen you might not want to do thisfrom some terminal types. 

-f Sets the file to find theportsand idsof connections. U sethisto specify a fi le other than /proc/net/tep. 

-1 Used to specify a fi le other than /etc/cident.users must beused with the -a option unlessyou like 

redundancy. 

-t Sets the timeout of a connection in seconds. This does not work in this versi on to cidentd. 
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If no argumentsarespecified, the program just runsas normal, almost likethe-n. 
cidentd -t 3a -a sets timer to 30 seconds and tellsitto look at .autmie files. 

FILES 

/etc/cidentd.users 
$(HOME)/.authlie 

SEEALSO 

identd(l) 

BUGS 

N onethat I know of. 

Linux/FreeBSD, M ay 1996 

cksum 

cksum— Checksum and countthebytes in afile 
SYNOPSIS 

cksum [ — help] [-version] [file...] 

D ESC RIFTIO N 

Thismanual page documents the GN U version of cksum. cksum computesacyclic redundancy check (CRC) for each named 
file, or the standard input if none are given orwhen a file named - isgiven. It printstheCRC for each file along with the 
number of bytesin the file, and thefilenameunless no argumentswere given. 

cksum istypically used to makesurethatfilestransferred by unreliablemeans(such asnetnews) havenot been corrupted. This 
isaccomplished by comparingthecksum output for the received files with thecksum output for the originai files. TheCRC 
algorithm isspecified by the PO SIX .2 standard. It isnot compatiblewith the BSD or System V sum programs; it ismore 
robust. 

Avai lableoptions are 

-heip Print ausagemessageand exit with a nonzero status, 

-version Print version information on standard output then exit. 

GNU Text Utilities 

clear 

ciear— Clear terminal screen 
SYNOPSIS 

clear 

DESCRIPTION 

ciear callstput(l) with the clear argument. Thiscausestput to attemptto clear the screen, checking the data in /etc/termcap 
(for the GN U or BSD tput) or in theterminto database (for the ncurses tput) and sending the appropriate sequenceto the 
terminal. Thiscommand can beredirected to clear the screen of some other terminal. 



co 



SEEALSO 

reset(l), stty(l), tput(l) 

AUTHOR 

Rik Faith (faithgcs.unc.edu) 

Linux 0.99, 10 October 1993 

cmuwmtopbm 

cmuwmtopbm— Convert aCM U window manager bitmap into a portable bitmap 
SYNOPSIS 

cmuwmtopbm [cmuwmfile] 

D ESC RIFTIO N 

Readsa CM U window manager bitmap as input. Produces a portable bitmap as output. 
SEEALSO 

pbmtocmuwm(l), pbm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

15 Aprii 1989 

CO 

co— C heck out RCS revisi ons 
SYNOPSIS 

co [options] file . . . 

DESCRIPTION 

co retrievesa revision from each RCS fi le and storesit into the corresponding working fi le. 

Pathnamesmatchingan RCS suffix denote RCS files; ali others denote working fi les. N amesarepaired asexplained in ci(l). 

Revisionsof an RCSfilecan bechecked out locked or unlocked. Locking a revision preventsoverlappingupdates. A revision 
checked out for readingor processing (for example, compii ing) need not be locked. A revision checked out for editing and 
later checkin must normally be locked. Checkout with locking failsif the revision to bechecked out iscurrently locked by 
another user. (A lock can bebroken with rcs(l).) Checkout with locking also requi res the Caller to beon the access list of the 
RC S fi le, unless he is the owner of the file or the superuser, or the access list is empty. C heckout without locking is not 
subjectto access list restrictions, and isnot affected by thepresenceof locks. 

A revision isselected by options for revision or branch number, checkin date/ti me, author, or state. W hen theselection 
options are appi ied in combination, co retri eves the latest revision that satisfi esali of them. If none of theselection options is 
specified, co retri eves the latest revision on the default branch, normally the trunk; seethe-b option of rcs(l). A revision or 
branch number can beattached to any of the options -f, -i, -ì, -m, -p, -q, -r, or -u. The opti ons -d (date), -s (state), and -w 
(author) retrievefrom a single branch, the selected branch (which is specified by -f or -u), or the default branch. 



A co command applied to an RCS file with no revisionscreatesazero-length working file, co always performs keyword 
substitution. 
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OPTIONS 

-r[rev] Retrieves the latest revision whosenumber is lessthan or equal to rev. If rev indicatesa branch 

rather than a revision, the latest revision on that branch is retri eved. If rev isomitted, the latest 
revision on the default branch is retri eved; seethe-b option of rcs(l). If rev is$, co determinesthe 
revision numberfrom keyword values in the working fi le. Otherwise, a revision iscomposed of one 
or morenumeric or symbol ic fields separateci by periods. If rev beginswith a peri od, then the 
default branch (normally thetrunk) isprepended to it. If rev is a branch number followed by a 
period, then the latest revision on that branch isused. Thenumeric equivalent of a sym bolic field is 
specified with the-n option of the commands cì(l) and rcs(l). 

-i[rev] Sameas-r, exceptthat it also locksthe retrieved revision for the Caller. 

-u[rev] Sameas-r, except that itunlocks the retrieved revision if it was locked by the Caller. If rev is 

omitted, -u retrievesthe revision locked bythecaller, if there is one; otherwise, it retrieves the latest 
revision on the default branch. 

-f [rev ] Forces the overwritingof the working fi le; useful in connection with -q. (Seealso "File M odes," 

later in thismanual page.) 

-kkv Generate keyword stri ngs usi ng the default form, forexample, $Revision: 5.13 $ for the Revision 

keyword. A locker's nameisinserted in thevalueof theHeader, id, and ucker keyword stri ngs only 
asafileisbeing locked, that is, by ci -ìandco -ì.Thisisthe default. 

-kkvi Like-kkv, except that a locker's nameisalwaysi nserted if thegiven revision iscurrently locked. 

-kk Generate only keyword namesin keyword stri ngs; omittheir values. (See"Keyword Substitution," 

later in this manual page.) Forexample, for theRevision keyword, generate the stri ng $Revision$ 
instead of $Revision: 5.13 $. T his option isuseful to ignoredifferencesdueto keyword substitu- 
tion when compari ng different revisions of a file. Log messages are i nserted after $i_og$ keywords 
even if -kk isspecified, si nce this tends to be more useful when merging changes. 

-ko Generate the old keyword stri ng, present in the working filejust before it was checked in. For 

example, for the Revision keyword, generate the stri ng $Revision: 1.1 $ instead of$Revision: 5.13 
$ if that ishow the string appeared when the fi le was checked in. Thiscan be useful forfileformats 
that cannottolerateany changes to substri ngs that happen to take the form of keyword stri ngs. 

-kb Generate a binary imageof the old keyword string. This acts li ke-ko, except it performs ali 

working file input and output in binary mode. This makes little difference on POSIX and U N IX 
hosts, but on D 0 S-like hosts one should usercs -i -kb to initializean RCS file normally refuses 
to mergefileswhen -kb isin effect. 

-kv Generate only keyword values for keyword stri ngs. Forexample, for the Revision keyword, generate 

thestring 5.13 instead of $Revision: 5.13 $. Thiscan help generate files in programmi ng languages 
whereit ishard to strip keyword del i m iters I i ke $Revision : $ from a string. H owever, further 
keyword substitution cannot be performed once the keyword namesareremoved, so this option 
should beused with care. Becauseof thisdangerof I osi ng keywords, thisoption cannot be 
combined with -1, and theowner wri te pernii ssion of the working fi le isturned off; to editthefile 
later, check it out again without -kv. 

-p[rev ] P ri nts the retri eved revision on the standard output rather than stori ng it in the working fi le This 

option isuseful when co ispartof a pipe. 

-q[rev] Quiet mode; diagnostics are not printed. 

-i[rev ] Interactive mode the user is prompted and questi oned even if the standard input is not a terminal. 

-ddate Retrievesthe latest revision on theselected branch whosecheckin date/ti me is lessthan or equal to 

date. Thedateand timecan begiven in free format. Thetimezonei_T standsfor locai time; other 
common timezonenamesareunderstood. Forexample, the followingdates are equivalent if locai 
timeisjanuary 11, 1990, 8 p.m. Pacific Standard Time, eight hourswest of Coordinated U ni versai 
Time(UTC): 



8:00 PM It 

4:00 AM, Jan. 12, 1990 



Default is UTC 



1990-01-12 04:00:00-K)0 
1990-01-11 20:00:00-08 
1990/01/12 04:00:00 
Thujan 11 20:00:00 1990 LT 
Thujan 11 20:00:00 PST 1990 
Fri Jan 12 04:00:00 GMT 1990 
Thu, 11 Jan 1990 20:00:00-0800 
12-January-1990, 04:00 W ET 

M ost fields in the date and timecan bedefaulted. The default ti me zone isnormally UTC, but thiscan beoverridden by the 
-z opti on. Theother defaults are determi ned in theorder year, month, day, hour, minute, and second (mostto least 
significanti. At least oneof these fields must be provided. For omitted fields that are of higher si gnifi canee than the highest 
provided field, thetimezone'scurrent valuesareassumed. Forali other omitted fields, the lowest possi blevalues are 
assumed. For example without -z, thedate20, 10:30 defaults to 10:30:00 UTC of the 20th of theUTC timezone'scurrent 
month and year. The date/ti me must bequoted if it contai ns spaces. 

-M[rev] Sets the modification timeon thenew working fi le to be the date of the retri eved revision. Usethis 

option with care it can confuse make(l). 

-sstate Retri eves the latest revision on theselected branch whose state is set to state. 

-t P reserves the modification ti me on the RC S fi le even if the RC S fi le changes because a lock is 

added or removed. T hi s option can suppress extensi ve recompilation caused by amake(l) depen- 
dency of some other copy of the working file on the RC S file. U se this option with care; it can 
suppress recompilation even when it isneeded, in other words, when thechangeof lock would 
mean achangeto keyword stri ngs in theother working fi le. 

-w[i agi n ] Retri eves the latest revision on theselected branch thatwaschecked in by the user with login name 

i o g i n. If theargument i ogi n is omitted, the cai ler's login is assumed. 

-jj oi ni i st Generatesa new revision which isthejoin of therevisionson j oi ni st . This option is largely made 

obsolete by rcsmerge(l), but isretained for backwards compati bility. 
The] oi ni i st isacomma-separated list of pairsof theform rev2: rev3, whererev2 and rev3 are 
(symbolic or numeric) revision numbers. Fortheinitial such pair, revi denotes the revision selected 
by theoptions-f, -w. Forali other pai rs, r evi denotes the revision generated by the previ ous pair. 
(Thus, the output of onejoin becomes the input to thenext.) 

Foreach pair, co j oi ns revi sionsr evi and r ev 3 with respectto r e v 2 . Thismeansthat ali changes that 
transform r e v 2 into revi are appi ied to a copy of r e v 3 . Thisis parti cularly useful if r ev ì and r ev 3 
aretheendsof two branchesthat haverev2 as a common ancestor. If revi<rev2<rev3 on thesame 
branch, joining generatesa new revision which is like r e v 3 , but with ali changes that lead from revi 
to r e v 2 undone If changes from rev2 to revi overlap with changes from r e v 2 to r e v 3 , co reports 
overlapsasdescribed in merge(l). 

Fortheinitial pair, r e v 2 can be omitted. The default is the common ancestor. If any of the 
argumentsindicatebranches, the latest revisionson those branches are assumed. Theoptions-i 
and -u lock or unlock revi . 
-v PrintsRCS'sversion number. 

-vn Emulates RCS version n, wheren can be3, 4, or 5. Thiscan be useful when interchanging RCS 

fileswith otherswho arerunning older versi onsof RCS. To see which version of RCS your 
correspondentsarerunning, havethem invokercs -v; thisworkswith newer versi onsof RCS. If it 
doesn'twork, havethem invokenog on an RCSfile; if noneof thefirst few linesof output contain 
thestring branch:, it is version 3; if thedates' years havejust two digits, it is version 4; otherwise, it 
is version 5. An RCS fi le generated whi le emulati ng version 3 losesits default branch. An RCS 
revision generated whi le emulating version 4 or earlier hasatimestamp that isoff by up to 13 
hours. A revision extracted whi le emulating version 4 or earlier contai ns abbrevi ated datesof the 
form yy/mm/dd and can also contain different whitespaceand li ne prefixes in thesubstitution for 
$Log$. 



ISO 8601 (UTC) 
ISO 8601 (locai time) 
Traditional RCS format 

Output Of ctime(3) +LT 
Output Of date(l) 

Internet RFC 822 
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-xs uf f i xes Usessuffixesto characterize RCS files. Seeci(l) for details. 

-zzone Specifies the date output format in keyword substitution, and specif ies the default ti me zonefor 

date in the-ddat e option. The zone should beempty, a numeric UTC offset, or the special stri ng 
lt for locai ti me The default isan empty zone, which uses the traditi onal RCS format of UTC 
without any timezoneindication and with slashes separati ng the parts of the date; otherwise, times 
are output in ISO 8601 format with timezoneindication. Forexample, if locai time isj anuary 11, 
1990, 8 p.m. Pacific Standard Time eight hourswest of UTC, then the ti me is output asfollows: 

Option Time Output 

-z 1990/01/12 04:00:00 (default) 

-zLT 1990-01 -11 20:00:00-08 

-z+05:30 1990-01-12 09:30:00+05:30 

The-z option does not affect datesstored in RCSfiles, which arealwaysUTC. 

KEYWORD SUBSTITUTION 

Stringsof the form $ keyword s and $ keywor d : ...$ embedded in thetextarereplaced with stringsof theform $ keyword 
: «ai ne $, where keyword and vai ne are pai rs in thefollowing list. Keywordscan be embedded in literal stringsor comments 
to identify a revision. 

Initially, the user enters stringsof theform $keyword$. On checkout, co replacesthese stri ngs with stringsof theform 
$keyword : «al ne$. If a revision containing stri ngs of the latter form ischecked back in, the v a i ne fieldswill bereplaced 
duri ng the next checkout. T hus, the keyword valuesareautomatically updated on checkout. T hi sautomatic substitution can 
be modified by the -k options. 

Keywords and their corresponding values: 

$Anthor$ Thelogin nameof the user who checked in the revision. 

$Da t e $ The date and ti me the revision was checked in. With -zzone, a numeric ti me zone offset is 

appended; otherwise, the date is UTC. 
$He a d e r $ A standard headercontainingthefull pathnameof the RCS file, the revision number, the date and 

time, theauthor, the state, and thelocker (if locked). With -zzone, a numeric ti me zone offset is 

appended to the date; otherwise, the date is UTC. 
$i d$ Sameas$Header $, except that the RC S filmarne is without a path. 

$l o c k e r $ Thelogin nameof the user who locked the revision (empty if not locked). 

$Log$ The log messagesupplied during checkin, preceded by a header containing the RCS filmarne, the 

revision number, theauthor, and the date and time. W ith -zzone a numeric ti me zone offset is 

appended; otherwise, the date is UTC. Existing log messagesarenot replaced. Instead, thenew log 

messageisinserted after $l o g : ... $ . Thisisuseful for accumulati ng a complete change log in a 

sourcefile. 

Each inserted li ne is prefixed by the string that prefixes the $l og $ line. Forexample, if the $Log$ line is// $i_og: tan.cc $, 
RCS prefixeseach I i ne of the log with / /.Thisisuseful for languageswith commmtsthat go to the end of the li ne The 
convmtion for other languages isto use a * prefix inside a multi line comment. For example, theinitial logcommmt of aC 
program conventionally is of thefollowing form: 

/* 

* $Log$ 

*/ 

For backwards compati bili ty with older versi onsof RCS, if the log prefix is /* or (* surrounded by optional whitespace, 
inserted log li nes contai n a space instead of / or c however, thisusageisobsolescent and should not be relied on. 

$Name$ Thesymbolic nameused to check out the revision, if any. Forexample, co -r Joegenerates$Name : 

joe $. Plain co generatesjust $Name : $. 



co [T] 

$Rcsf m e$ Thenameof the RC S file without a path. 

$Revision$ The revision numberassignedto the revision. 

$so u r c e $ Thefull pathname of the RC S file. 

$s t a t e $ The state assi gned to the revision with the-s option of rcs(l) or ci(l). 

Thefollowingcharacters in keyword valuesarerepresented by escape sequen cesto keep keyword stringswell-formed. 

Character Escape Sequence 

tab \t 
newline \n 
space \04B 

$ \044 

\ w 
FILEMODES 

T he working file inherits the read and executepermissionsfrom the RC S fi le. In addition, theownerwritepermission is 
turned on, unless-kv is set or the file is checked out unlocked and locking is setto stri et; sea rcs(l). 

If a file with thenameof the working file exists al ready and haswrite perni ission, co abortsthecheckout, asking beforehand 
if possible. If the existing working file is not writable or -f isgiven, theworkingfileisdeleted without asking. 

FILES 

co accessesfilesmuch asci(l) does, except that it doesnot need to read the working fi le unless a revision number of $ is 
speci fi ed. 

ENVIRONMENT 

rcsinit Optionsprepended to theargument list, separated by spaces. Seeci(l) for details. 

DIAGNOSTICS 

T he RCS pathname, the working pathname, and the revision number retri eved arewritten to the diagnostic output. The exit 
statusiszero if and only if ali operationsweresuccessful. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.13; Release D ate: 1995/06/01. 

Copyright © 1982, 1988, 1989 Walter F. Tichy. 

Copyright © 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 

SEEALSO 

rcsintro(l), ci(l), ctime(3), date(l), ident(l), make(l), rcs(l), rcsclean(l), rcsdiff(l), re -smerge(l), rlog(l), rcsfile(5) 

Walter F. Tichy, "RCS-A System for V ersi on Control," Software P racti ce & Experiencel5, 7 (July 1985), 637-654. 
LIMITS 

Links to the RC S and working files are not preserved. 

There isno way to selectively suppresstheexpansion of keywords, except by writing them differently. In nroff and troff, 
thisisdoneby embeddingthenull-character \& into the keyword. 

GNU, 1 Junel995 
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col 

col— Filter reverse linefeedsfrom input 
SYNOPSIS 

col [ -bf x] [ -1 n u iti] 

D ESC RIPTIO N 

coi filters out reverse (and half-reverse) linefeeds so the output isin thecorrect order with only forward and half-forward 
linefeeds, and replaceswhitespacecharacterswith tabs where possi ble. T hi scan beuseful in processing the output of 
nroff(l) and tbi(l). coi readsfrom standard input and writesto standard output. 

The opti ons are as follows: 

-b Do not output any backspaces, printing only the last character written to each column position. 

-f Forward half-linefeeds are permitted (fine mode). N ormally characters printed on a half-line boundary 

areprinted on thefollowing line, 
-x Output multi pie spaces i nstead of tabs. 

-inulti Buffer at least num linesin memory. By default, 128 linesarebuffered. 

The control sequencesfor carri age moti on thatcoi understands and their decimai values are listed in thefollowing table 



Control Sequence 


Dedmal Value 


Esc+7 


Reverse line feed (escape then 7) 


Esc 46 


Half-reverse li ne feed (escape then 8) 


Esc-h9 


H alf-forward linefeed (escape then 9) 


Backspace 


Moves back one column (8); ignored in the first column 


Carri age return 


(13) 


N ewline 


Forward linefeed (10); also doescarriage return 


Shiftin 


Shift to normal character set (15) 


Shiftout 


Shift to alternate character set (14) 


Space 


M oves forward one column (32) 


Tab 


M oves forward to next tab stop (9) 


V erti cai tab 


Reverse linefeed (11) 



Ali unrecognized control characters and escape sequences are discarded. 

coi keepstrack of the character set as characters are read and makessure the character set iscorrect when they are output. 
If the input attemptsto back up to the last flushed line, coi will display a warning message. 

SEE ALSO 

expand(l), nroff (1), tbl(l) 

HISTORY 

A coi command appeared in version 6 AT&T U N IX. 

17Junel991 
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colcrt 

coicrt— Fi Iter nroff output for C RT previ ewing 
SYNOPSIS 

colcrt [-] [-2] [file . . .] 

D ESC RIFTIO N 

coicrt provi des virtual half-line and reverse- li ne feed sequencesforterminalswithoutsuch capability, and on which 
overstriking isdestructive H alf-linecharactersand underlining (changed to dashing -) areplaced on new lines in between 
thenormal output lines. 

Avai lable options: 

Suppressall underlining. Thisoption i s especi al ly useful for previewing ali boxed tablesfrom tbi(l). 
-2 Causesall half-linesto beprinted, effecti vely doublé spacing the output. Normally, a minimal space 

output format isused which wi II suppressempty lines. The program neversuppressestwo consecutive 
empty lines, however. The -2 option is useful for sending output to theline printer when the output 
containssuperscriptsand subscriptsthatwould otherwise be invisible 

EXAMPLES 

A typical useof coicrt would be 

tbl exum2.n ] nroff -ms | colcrt - | more 

SEEALSO 

nroff(l), troff(l), col(l), more(l), ul(l) 

BUGS 

Should fold underlinesonto blankseven with the - option so that a trueunderlinecharacter would show. 
Can'tback up morethan 102 lines. 

General overstriking is lost; asa special case | overstruck with 1 or underline becomes+. Linesaretrimmed to 132 
characters. 

Some provision should bemadefor processing superscriptsand subscriptsin documentsthat arealready double-spaced. 
HI STORY 

Thecoicrt command appeared in BSD 3.0. 

BSD 3, 30 junel993 

colrm 

coirm— Remove columnsfrom afile 
SYNOPSIS 

colrm [st art col [endcol ] ] 

DESCRIPTION 

coirm removesselected columnsfrom afile. Input istaken from standard input. Output is sent to standard output. 

If called with one parameter, thecolumnsof each li ne wi II beremoved starti ng with the specified column. If called with two 
parameters, the columnsfrom the first column to thelast column will beremoved. 

Column numbering starts with column 1. 
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SEEALSO 

awk(l), column(l), expand(l), paste(l) 

HISTORY 

The coi™ command appeared in BSD 3.0. 

BSD 3, 14 March 1991 

column 

coiumn— C olumnate lists 
SYNOPSIS 

column [-tx] [ -ce o I u mn s ] [ -ss e p ] [...file] 

D ESC RIFTIO N 

Thecoiumn utility formatsits input into multiplecolumns. Rowsarefilled beforecolumns. Input istaken from fileoperands, 
or, by default, from the standard input. Empty lines are ignored. 

The opti ons are asfollows: 

-c Output isformatted for a display columnswide 

-s Specify a set of charactersto beused to delimit columnsfor the -t opti on. 

-t D etermi ne the number of columns the input contai ns and create a table. C olumns are delimited with 

whitespace, by default, or with the characters supplied usingthe-s option. Useful for pretty-printing 

displays. 

-x Fili columns beforefilling rows. 

C olumn exits 0 on success, >o if an errar occurred. 

ENVIRONMENT 

Theenvironment variable columns isused to determi ne the sizeof the screen if no other information isavailable. 
EXAMPLES 

(printf "PERM LINKS OWNER SIZE MONTH DAY HH:MM/YEAR NAME"; ls -1 j sed 1d) j column -t 

SEEALSO 

colrm(l), ls(l), paste(l), sort(l) 

HISTORY 

Thecoiumn command appeared in BSD 4.3 Reno. 

6 Junel993 

comm 

comm— Compare two sorted files line byline 
SYNOPSIS 

comm [-123] [ — help] [— version] fi lei f i I e 2 



convdate 



DESCRIPTION 

Thismanual page documents the GN U version of coi™, coi™ prints lines that are common, and linesthat areunique, to two 
input files. Thetwo files must besorted beforecomm can beused. Thefilename- means the standard input. 

Witti no options, coi™ producesthreecolumn output. Column one contai ns li nesuniqueto fi lei, column two contai ns 
lines uni queto f i i ti, and column threecontains lines common to both files. 

OPTIONS 

Theoptions-1, -2, and -3 suppress printingof thecorrespondingcolumns. 
-heip Print ausagemessageand exit with a nonzero status, 

-version Print version information on standard output then exit. 

GNU Text Utilities 

convdate 

convdate— C onvert ti me/date stri ngs and numbers 
SYNOPSIS 

convdate [ -c ] [-n ] [-s ] a r g . . . 

DESCRIPTION 

convdate translates the date/time strings specified asargumentson its command line, outputti ng the results one to a line. 

If the-s flag isused, then each argument istaken as a date stri ng to beparsed by parse-date(3) and is output asastring 
formatted by ctime(3). This is the default. 

If the-n flag isused, then each argument isconverted thesameway but is output asatimet; seetime(2). 

If the-c flag isused, then each argument istaken to beatimet and is output in ctime format. 

Here's an example 

% convdate 1 f eb 10 10am 
Sun Feb 10 10:00:00 1991 

% convdate 12pm 5/4/90 
Fri Dee 13 00:00:00 1991 
Fri May 4 00:00:00 1990 

% convdate -n 'feb 10 10am' 1 2pm 5/4/90 

666198000 

641880000 

% convdate -c 666198000 
Sun Feb 10 10:00:00 1991 

HI STORY 

Written by Rich $alz (rsalzguunet.uu.net). 

SEEALSO 

parsedate(3) 




Parti: U ser Commands 



cp 

cp— Copy files 

SYNOPSIS 

cp [options] source dest 

cp [options] source... directory 

Options: 

[-abdfilprsuvxPR] [-S backup-suffix] [-V fnumbered,existing,simpleg] [-backup] 
[ -no-dereference] [-force] [ - interactive] [ — one-file-system] [ — preserve] 
[ -recursive] [ — update] [-verbose] [ — suffix=backup-suffix] 
[ — version-control=fnumbered,existing,simpleg] [ — archive] [ — parents] [—link] 
[ — symbolic-link] [ — help] [— version] 



DESCRIVO N 

Thismanual page documents the GN U version of cp. If thelast argument namesan existing directory, cp copieseach other 
given fileinto afilewith thesamenamein that directory. Otherwise, if only two files are given, it copies the first onto the 
second. It isan errar if thelast argument isnot a directory and morethan two files are given. By default, it doesnot copy 
di recto ri es. 



OPTIONS 

-a, -archive 

-b, -backup 

-d, —no-dereference 

-f, —force 
-i, -interactive 
-1, -link 
-P, -parents 



-p, —preserve 
-r 

-s, —symbolic-link 

-u, -update 

-v, —verbose 

-x, —one-file-system 

-R, —recursive 

— help 

— version 

-S, -suffix backup-suffix 



P reserve asmu eh as possi bleof the structure and attri butes of theoriginal filesin the copy. 
Thesameas-dpR. 

M ake backupsof files that are aboutto beoverwritten or removed. 

Copy sym boli c links assymbolic links rather than copying the files that they point to, and 

preserve hard link relationships between source files in thecopies. 

Remove existing desti nati on files. 

Promptwhetherto overwrite existing regulardestination files. 

M ake hard linksinstead of copiesof nondirectories. 

Form thenameof each desti nation fileby appendi ng to the target directory a si ash and the 
speci fi ed nameof the source fi le. Thelast argument given to cp must be thenameof an 
existing directory. For example thecommand cp -parents a/b/c existing_dir copies the 
file a/b/c to existing_dir/ a/b/c, creati ngany missing intermediate di rectories. 
Preserve the originai files' owner, group, permissions, and timestamps. 
C opy directories recursively, copying ali nondirectories as if they were regular files 
M ake sym boi ic links instead of copiesof nondirectories. Ali source filenames must be 
absolute (starti ngwith /) unless the desti nation files are in thecurrent directory. This 
option producesan errar messageon systemsthat do not support symbolic links. 
Do not copy a nondirectory that hasan existing desti nation with thesameor newer 
modification time 

P ri nt the name of each fi le before copyi ng it. 

Skip subdi rectories that areon differentfilesystemsfrom the one that the copy started on. 
Copy directories recursivéy. 

P ri nt a usage messageon standard output and exit successfully. 

Print version information on standard output then exit successfully. 

The suffix used for maki ng si mple backup fi les can be set with the simple_backup_suffix 

environment variable, which can beoverridden by this opti on. If neither of thoseis given, 

the default is-, asit is in emacs. 
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-v, -version-controi T he type of backups made can be set with the version_control environment variable, which 

{numbered,existing,simpie> can be overridden by thisoption. If version_control isnot set and thisoption isnot given, 
the default backup type is existing. T he value of the version_control envi ronment variable 
and theargumentto thisoption are liketheGN U emacs version- control variable; they 
also recognizesynonymsthat aremoredescriptive. The vai id values are (unique abbrevi a- 
tionsareaccepted) thefollowing: 

t or numbered Always make numbered backups 

mi or existing M ake numbered backups of fi lesthat already havethem, 

si mple backups of the others 
never or simpie Always makesimple backups 

cccp, cpp 

cccp, cpp— TheGNU C-compatiblecompiler preprocessor 
SYNOPSIS 

cccp [ -$ ] [ —A predi cate [(value ) ] ] [ -C ] [-D na me [ = definition ] ] 
[ -dD ] [ -dM I [ -I \ directory ][-H ][-I- ] [-imacros file ][- 
include file ] [-idirafter di r ] [ -ipref ix p r e f i x ] [-iwithpref ix di r ] 
[ -lang-c] [-lang-c++] [-lang-objc ] [-lang-objc++ ][-lint ][- 
M[-MG ] ] [ -MM[-MG ]] [ -MD file ] [-MMD file ] [-nostdinc ] 
[ -nostdinc++] [-P] [-pedantic ] [-pedantic-errors ] [-traditional ] 
[ -trigraphs ][-U nane ][-undef ] [-Wtrigrapbs ][-Wcomment ] 
[ -Wall ] [-Wtraditional ] 
[ nf i I e |- ] [ o u t f i I e |- ] 

DESCRIVO N 

TheC preprocessor isa macro processorthat isused automatically bytheC compilertotransform your program before 
actual compilation. It iscalled a macro processor becauseit allowsyou to define macros, which are bri ef abbreviationsfor 
longer constructs. 

TheC preprocessor providesfour separate faci litiesthatyou can useasyou seefit: 

■ Inclusion of header files. Thesearefilesof declarationsthat can besubstituted into your program. 

■ M acro expansion. You can define macros, which are abbreviationsfor arbitrary fragmentsof C code, and then theC 
preprocessor wi II replace the macros with their definiti onsthroughout the program. 

■ Conditional compilation. Using special preprocessing di recti ves, you can i nclude or exclude parts of the program 
accordi ng to various conditions. 

■ Li ne control. If you use a program to combine or rearrangesource files into an intermediate fi le which is then compi led, 
you can use line control to inform the compiler of whereeach source I i ne originally camefrom. 

C preprocessors vary in somedetails. For afull explanation of theGN U C preprocessor, see the info file cpp. info, or the 
manual TheC Preprocessor . Both of thesearebuilt from thesamedocumentation source fi le, cpp.texinfo. TheGN U C 
preprocessor providesa superset of thefeaturesof AN SI Standard C . 

ANSI Standard C requi res the rei ecti on ofmany harmless constructs commonlyused bytoday'sC programs. Such 
incompatibility would beinconvenientforusers, sotheGNU C preprocessor is con fi gured to acceptthese constructs by 
default. Strictly speaking, to get AN SI Standard C, you must usetheoptions-trigrapbs, -undef, and -pedantic, but in 
practicetheconsequencesof having strict AN SI Standard C makeit undesirableto do this. 

When you use the C preprocessor, you will usually not haveto invokeit explicitly: theC compiler will do so automatically. 
H owever, the preprocessor issometimesuseful indivi dually. 

W hen you cali the preprocessor individually, either name(cpp or cccp) will do; they are compi etely synonymous. 



Parti: U ser Commands 



TheC preprocessor expectstwo filenamesasarguments, infiie and outf ile. The preprocessor readsinfiie together with 
any other files it specifies with «include. Ali the output generated by the combined input fi les is written in outf ile. Either 
infiie or outf ile may be-, which as infiie meansto read from standard input and as outf ile meansto writeto standard 
output. Also, if outf ile or both filenamesareomitted, the standard output and standard input areused for the orni tted 
filenames. 

OPTIONS 

H ere isa table of command optionsaccepted by theC preprocessor. Theseoptionscan also begiven when compilingaC 
program; they are passed along automati cally to the preprocessor when it is invoked by the compiler. 

-p Inhi bit generation of # lineswith line-number information in the output from the preprocessor. 

Thismight beuseful when running the preprocessor on something that isnot C code and will be 
sent to a program which might beconfused by the# lines. 

-c Do not discard comments: pass them through to the output fi le. Commentsappearing in 

argumentsof a macro cali will becopied to the output beforetheexpansion of themacro cali. 

-traditionai Try to imitate the behavior of old-fashioned C, asopposed to AN SI C. 

-trigrapns ProcessAN SI standard trigraph sequences. Thesearethree-character sequences, ali starting with ??, 

that are defi ned by AN SI C to stand for single characters. For example, ??/ standsfor \, so ??/n isa 
character Constant fora newli ne. Strictly speaking, theGN U C preprocessor does not supportali 
programsin AN SI Standard C unless -trigrapns isused, but if you ever noticethedifference, it 
will bewith relief. You don'twant to know any more about trigraph s. 

-pedantic Issue warnings required by the AN SI C standard in certain casessuch as when text other than a 

COmment follOWS#else Or#endif. 

-pedantic-errors Like -pedantic, except that errors are produced ratherthan warnings. 

-wtrigrapns Warn if any trigraphs are encountered (assumi ng they are enabled). 

-wcomment Warn whenever a comment-start sequence /* appears in acomment. (Both formshavethe 

-wcomments sameeffect.) 

-Wall RequestS both -Wtrigrapns and -Wcomment (but not -Wtraditional). 

-wtraditionai Warn aboutcertain constructs that behave differently in traditionai andANSI C. 

-i directory Add the directory di rectory to the end of the list of directoriesto besearched for header files. This 

can beused to overridea system header file, substitutingyour own versi on, sincethese directories 
aresearched before the system header file directories. If you use more than one-i option, the 
directories are scanned in left-to-right order; thestandard system directories come after. 

-i- Any di recto ri es speci fi ed with -i options before the -i- option aresearched only for the case of 

«include " file ■; they are not searched for «include < file >. 

If additional directories are specified with -i options after the -i-, these di rectories are searched for 
ali «include di rectives. 

In additi on, the-i- option i nhibits the use of the current directory as the first search directory for 
«include - file '. T herefore, the current di rectory is searched only if it is requested explicitly with 
-i followed by a period (.). Specifying both -i- and -i. allowsyou to control preci sely which 
directories are searched before the current one and which aresearched after. 

-nostdinc Do not search thestandard system di rectories for header files. Only the directories you have 

specified with -i options (and the current di rectory, if appropriate) aresearched. 

-nostdinc++ Do not search for header fi les in theC+-r-specific standard directories, but do stili search the other 

standard directories. (Thisoption isused when buildi ng iibg++.) 

-d name P redef i ne n a me asa macro, with definition 1. 

-d n a me =d ef i ni t i on P redef ine name as a macro, with definition defi ni t on.Thereareno restri ctionson thecontentsof 
definition, but if you are invoking the preprocessor from ashell or shell-like program, you may 
need to use the shell's quoti ngsyntaxto protect characters such asspacesthat have a meaning in 
theshell syntax. If you use more than one-D for the same name, the ri ghtmost definition takes 
effect. 
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Do not predefinename. If both -u and -d are specified for onename, the-u beatsthe-D and the 

nameisnotpredefined. 

Do notpredefineany nonstandard macros. 

Assert (in thesameway asthe#assert directive) the predicate nam e with tokeniist value. 

Remember to escape or quote the parentheseson shell command lines. You can use -a- to disable 

ali predefined assertions; italso undefinesall predefined macros. 

Instead of outputtingtheresult of preprocessing, output a list of #define di recti ves for ali the 

macros defi ned duringtheexecution of the preprocessor, including predefined macros. T hi sgi ves 

you away of findingout what is predefined in your version of the preprocessor; assumingyou have 

no fi le f oo. h, the command 

touch foo.h; cpp -dM foo.h 

will show thevaluesof any predefined macros 

Like-dM except in two respects: it doesnot include the predefined macros, and it outputsboth the 
#define di recti ves and the result of preprocessing. Both kindsof output go to the standard output 
file. 

Instead of outputtingtheresult of preprocessing, output a rulesuitablefor make describi ng the 
dependenciesof the mai n source fi le. The preprocessor outputsone make rulecontainingthe 
objectfilenameforthatsourcefile, a colon, and thenamesof ali theincluded files. If there are 
many included files then the mie is split into several lines usi ng \\ (navi ine). 
-MGsaystotreatmissingheaderfilesasgeneratedfilesandassumetheyliveinthesamedirectoryas 
the source fi le. It must be specified in addition to -u. 
Thisfeatureisused in automatic updating of makefiles. 

Like-M but mention onlythefiles included with «include ■ file ".System header files i ncluded 
with #inciude < file >areomitted. 

Like-M butthedependency information iswritten to file. T his is in addition to compi li ng the fi le 
as specified. -md does not inhibit ordinary compilation theway -m does. 
When invokinggcc, do not specify thef i e argument. gcc will create fi lenamesmadeby replacing 
.c with .d at the end of the input fi lenames. 

In M ach, you can use the utility md to merge multi pie files into a single dependency file suitable for 
usi ng with the make command. 

Like-M except mention only user header files, not system header files. 
Printthenameof each header file used, in addition to other normal activities. 
Processfileasinput, di scardi ng the resulti ng output, before processing the regular input file. 
Because the output generated from fileisdiscarded, the only effect of -imacros file isto make the 
macros defi ned in file avai lablefor use in the mai n input. The preprocessor evaluates any -d and -u 
optionson the command line before processing -imacros fi le. 

Processf i i e as input, and include ali the resulting output, before processing the regular input file. 
Add the directory di r to thesecond include path. Thedirectorieson thesecond include path are 
searchedwhen a header file is not found in any of the directories in themain include path (theone 
that -i addsto). 

Specify p refi x asthe prefix for subsequent -iwitnprefix options 

Add a directory to thesecond include path. Thedirectory'snameismadeby concatenati ng prefix 
and dir, where prefix was specified previously with -iprefix. 

Specify the source language. -iang-c++ makes the preprocessor handle C ++ comment syntax, 
and includes extra default include directories for C++, and -ìang-objc enablestheObjectiveC 
«import directive. -iang-c expl icitly turns off both of theseextensions, and -iang-objc++ enables 
both. These options are generated by thecompiler driver gcc, but not passed from thegcc 
command line. 

Look for commandsto the program checker lint embedded in comments, and emitthem preceded 
by#pragma lint. For example, the comment /* notreached */ becomes #pragma lint notreached. 
Thisoption is avai lable only when you cali cpp directly; gcc will not pass it from its command line. 



Parti: U ser Commands 



-$ Forbid the use of $ in identifiers. This isrequired for AN SI conformance. gcc automati cally 

supplies this option to the preprocessor if you specify -ansi, but gcc doesn't recognizethe-$ 
option itself; to use it without the other effects of -ansi, you must cali the preprocessor di recti y. 

SEEALSO 

cpp entry in info; TheC Preprocessor, Richard M . Stali man. 

gcc(l); gcc entry in info; Using and Porting GNU CC (for version 2.0), Richard M . Stallman. 
COPYING 

Copyright © 1991, 1992, 1993 Free Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim 
copiesof thismanual provided the copyright noticeand this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof thismanual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof thismanual into another language, under the above conditions 
for modifi ed versi ons, except that this permission notice may beincluded in translationsapproved by the Free Software 
Foundation instead of in theoriginal English. 

GNU Tools, 30 Aprii 1993 

crontab 

crontab— M ani pulate per-user crontabs (D illon'sCron) 
SYNOPSIS 

crontab file [ - u user] Replacecrontab from file 

crontab - [-u user] Replacecrontab from stdin 

crontab -1 [user] List crontab for user 

crontab -e [user] Edit crontab for user 

crontab -d [user] D elete crontab for us e r 

crontab -c dir Specify crontab di rectory 

DESCRIPTION 

crontab mani pulates the crontab for a particular user. Only thesuperuser may specify a different user and/or crontab 
directory. General ly, the - e option isused to edit your crontab. crontab wi II use /usr/bin/vi or the editor specified by your 
VISUAL environment variableto edit the crontab. 

U nlike other crond/crontabs, this crontab doesnottry to do everything under the sun. Frankly, ashell script ismuch more 
ableto mani pulate the environment than cron, and I seeno particular reason to usetheuser'sshell (from his password entry) 
to run cron commands when this requires special casingof nonuser crontabs, such asthosefor U UCP. When a crontab 
command isrun, thiscrontab runsitwith /bin/sti and setsup only three environment vari ables: user, home, and shell. 

crond automati cai ly detects changes in the ti me. R everse- indexed timechangeslessthen an hour old will N OT rerun crontab 
commandsalready issued in therecovered period. Forward-indexed changes lessthen an hour into the future will issue 
missed commands exactly once. Changes greaterthen an hour into thepast or future cause crond to resynchronizeand not 
issue mi ssed commands. N o attempt will bemadeto issue commands lost due to a reboot, and commands are not reissued if 
thepreviously issued command is stili running. For example, if you have a crontab command sieep 70 that you wish to run 
once a minute, cron will only be ableto issue the command onceevery two minutes. If you do not likethisfeature, you can 
run your commands in the background with an &. 




Thecrontab format isroughly similarto that used by vixiecron, but without complexfeatures. Individuai fields may contai n 
a ti me, atimerange, atimerangewith a skipfactor, asymbolic rangefor the day of week and month in year, and additional 
subranges delimited with commas. Blank li nes in thecrontab or linesthat begin with a hash (#) areignored. If you specify 
both a day in the month and a day of week, the result iseffectively oRd; thecrontab entry wi II berun on the specified day of 
week and on the specified day in themonth. 

# MIN HOUR DAY MONTH DAYOFWEEK COMMAND 

# at 6:10 a.m. every day 
10 6 ***date 

# every two hours at the top of the hour 
0 */2 ***date 

# every two hours from 11p.ni. to 7a.m., and at 8a.m. 

0 23-7/2,8 ***date 

# at 11:00 a.m. on the 4th and on every mon, tue, wed 
0 11 4 * mon -wed date 

# 4:00 a.m. on january 1 st 
0 4 1 jan *date 

# once an hour, ali output appended to log file 
0 4 1 jan *date»/var/log/messages 2>&1 

Thecommand portion of thelineisrun with /bin/sn -c <command>, and may therefore contai n any valid Bourneshell 
command. A common practiceisto run your command with exec to keep theprocesstableuncluttered. It isalso common to 
redirect output to a log fi le. If you do not, and thecommand generates output on stdout or stderr, the result wi II bemailed 
to the user in question. If you usethis mechanism for special users, such asUUCP, you may want to create an alias for the 
user to direct the mail to someoneelse, such as root or postmaster. 

Internally, thiscron usesa quick indexing system to reduce CPU overhead when lookingfor commandsto execute. Several 
hundred crontabswith several thousand entriescan behandled without usi ng noti ceable CPU resources. 

BUGS 

Oughtto beableto have several crontabfilesforanygiven user, asan organizational tool. 
AUTHOR 

M atthew D illon (dillongapollo.west.oic.com) 

1 May 1994 

esplit 

cspiit— Split a file into sections determi ned by context lines 
SYNOPSIS 

esplit [-sqkz] [-f prefix] [-b suffix] [-n digits] [ — pref ix=pref ix] 
[ -suff ix-f ormat=suff ix] [ -digits=digits] [— quiet] [ — silent] 
[ -keep-files] [ -elide-empty-f iles] [-help] [ — version] 
file pattern. . . 

DESCRIVO N 

Thismanual page documents the GN U version of cspiit. cspiit createszero or more output files contai ning sections of the 
given input file, or the standard input if thename- isgiven. By default, esplit printsthenumber of byteswritten to each 
output fi le after it hasbeen created. 
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Thecontents of the output fi les are determi ned by the pattern arguments. An errar occursif a pattern argument refersto a 
nonexistent lineof the input file, such asif no remai ning linematchesagiven regular expression. After ali thegiven patterns 
havebeen matched, any remai ning output iscopied into onelast output file. The typesof pattern arguments are 

ime Create an output fi le contai ning the current lineup to (but not includi ng) line une (a positive 

integer) of theinputfile If followed by a repeat count, also create an output filecontainingthe 
next line lines of the input file oncefor each repeat. 

/regexp/ [offset] Create an output fi le contai ning the current lineup to (but not includi ng) the next lineof the 
input filethat contai ns a match for regexp. The optional offset isa + or - followed by a positive 
integer. If it isgiven, the input up to thematching line plus or mi nus offset isput into the output 
file, and the li ne after that begins the next section of input. 

%regexp%[offset] Like the previ oustype, except that itdoes not create an output file, so that section of theinputfile 
iseffectively ignored. 

{repeat -count} Repeat the previ ous pattern repeat -count (a positive integer) additional times. An asterisk may be 

given in place of the (integer) repeat count, in which case the precedi ng pattern isrepeated asmany 
timesas necessary until the input isexhausted. 

The output fi lenamesconsistof a prefix followed by asuffix. By default, thesuffix ismerely an ascendi ng linear sequenceof 
two-digit decimai num bers starti ngwith 00 and rangingup to 99; however, this default may beoverridden by either the - 
digits option orby the -suffix-format option. (See"Options," next.) In any case, concatenati ng the output fi les in sorted 
order by fi lename produces the origi nal i nput fi le i n order. The default output fi lename prefix is xx. 

By default, if esplit encountersan errar or receivesa hangup, interrupt, quit, or termi nate signal, it removesany output fi les 
that it has created so far before it exits. 



0PTI0NS 

-f, — prefix=pr ef i x 

-b, — suf f ix-f ormat=s uf f i x 



-n, — digits=d g ts 

-k, — keep-files 

-z, -elide-empty-files 



-s, -q, -silent, 
— help 
— version 



-quiet 



Usepref i x as the output fi lename prefix string. 

Use suf f i x as the output fi lename suffix string. W hen this option isspecified, thesuffix string 
must include exaetlyoneprintf (3) style conversi on specification (such as%d, possibly includi ng 
format specificati on flags, afield width, a precisi on specifications, orali of thesekindsof 
modifiers). Theconversion specification must besuitablefor converti ng a binary integer 
argument to readableform. Thus, only d, i, u, o, x, and x format specifiers are allowed. The 
enti re suffix string isgiven (with the current output file num ber) to sprintf(3) to form the 
fi lename suffixes for each of the individuai output filesin turn. Note that when this option is 
used, the -digits option is ignored. 

Use output filenamescontaini ng numbers that are di gì t s digits long in stead of th e def au 1 1 2 . 
Do not remove output fi les when errorsareencountered. 

Suppress the generation of zero-iengtn output files. (In caseswhere the section delimiters of the 
input file are supposed to mark the first linesof each of the sections, the first output file wi II 
generally beazero-iengtn fileunlessyou use this option.) N ote that the output file sequence 
numbers will alwaysrun consecutively, starti ng from 0, even in caseswhere zero -ìengtn output 
sections are suppressed dueto the use of this option. 
D o not print counts of output filesizes. 
Print ausagemessageand exit with a nonzero status. 
Print version information on standard output, then exit. 
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ctags -Generatestags and {opti onally) refs file 
SYNOPSIS 

ctags [-BSstvraT] fi I e s n a me s . . . 

D ESC RIPTIO N 

ctags generatesthetagsand refs files from a group of C source files. Thetags fileisussd by theeivis :tag command, 
control-] command, and -t option. The refs fileissometimesused bytheref(l) program. 

Each C source fi le isscanned for #define statementsand global function definitions. Thenameof themacro orfunction 
becomesthenameof atag. For each tag, a lineisadded to thetags filethat contai ns the following: 

■ Thenameof thetag 

■ A tab character 

■ The nam e of the fi le contai ni ng the tag 

■ A tab character 

■ A way to find the particular linewithin thefile 

Thef m enames list wi II typically bethenamesof ali C source files in the current directory, likethis: 
$ ctags -stv *. [eh] 

OPTIONS 

-b Normally, ctags enclosesregularexpressions in slashes(/regexp/), which causeseivis to search from the 

top of thefile. The -b flag causes ctags to enclosetheregular expressionsin question marks(?regexp?) so 

eivis wi II search backward from the bottom of thefile. This rarely matters 
-t Include typedefs. A tag wi 1 1 begenerated for each user-defi ned type. Alsotagswill begenerated forstruct 

and enum names. Typesareconsidered to be global if they are defined in a header file, and stati c if they are 

defined in aC source fi le. 

-v Include vari abledeclarations. A tagwill begenerated for each variable, except forthosethat aredeclared 

inside the body of a function. 

-s Include stati c tags ctags wi 1 1 normally put global tags in thetags file, and silently ignore the stati ctags. 

This flag causes both global and stati c tags to beadded. Thenameof a stati c tag isgenerated by prefixing 

thenameof the declared item with thenameof the file whereit is defined, with acolon in between. For 

example, static foooo in bar.c resultsin atag named bar.cifoo. 
-s Include static tags, but makethem look like global tags. M ost tags-awareprogramsdon't li ke the 

fiiename:tagname tags produced by the -s flag, so -s wasadded asan alternative. If eivts and ref are the 

only programsthat read thetags file, then you don'tneed -s; otherwise, you do. 
-r This causes ctags to generate both tags and refs. W ithout -r, itwould only generate tags. 

-a Append to tags, and mayberefs. N ormally, ctags overwritesthese files each timeit is invoked. This flag is 

useful when you havetoo many files in the current directory for you to list them on a single command 

line; it allowsyou to split theargumentsamongseveral invocations. 
-t Thisflag isn't availableon ali systems. U N IX hasit, but most othersdon't. The -t flag prevents ctags 

from generati ng a tags file This is useful when you want to generate a refs without changingtags. 

FILES 

tags A cross-referencethat lists each tag name, thenameof the source filethat contai nsit, and a way to locate a 

particular line in the source fi le. 
refs The refs file contai nsthedefi nitionsfor each tag in thetags file and very little else. This file can be 

useful, for example, when licensing restrictions prevent you from making the source code to thestandard 

C library readableby everybody, but you stili want everybody to know whatargumentsthe library 

functionsneed. 
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BUGS 

ctags issensitiveto indentingand line breaks. Consequently, itmightnot discover ali ofthetagsin afilethat isformatted in 
an unusual way. 

SEEALSO 

elvis(l), refs(l) 

AUTHOR 

Steve K i rkendal I (kirkenda§cs . pdx . edu) 

cu 

cu— Cali up another system 
SYNOPSIS 

cu [ options ] [ system j phone ] "dir" ] 

D ESC RIFIO N 

The cu command isused to cali up another system and act asadial in terminal. It can also do simple file transfers with no 
error checking. 

cu takes a single argument, besides the options. If theargument is the stringa r, cu will make a direct connection to theport. 
This may only be used by users with write access to the port, as it permits reprogramming the modem. 

Otherwise, if theargument begins with a digit, it istaken to bea phone numberto cali. Otherwise, it istaken to bethename 
of a system to cali. The -z or - system option may beused to name a system beginningwith a digit, and the-c or - phone 
option may beused to name a phone num ber that doesnot begin with a digit. 

cu locatesa portto use in theUUCP confi guration files. If a simple system nameisgiven, itwill select a port appropri atefor 
that system. The -p, -port, -1, -line, -s, and -speed options may beused to control theport selection. 

When a connection ismadeto the remote system, cu forks into two processes. Onereadsfrom theport and writesto the 
terminal, whilethe other readsfrom theterminal and writesto theport. 

cu provides several commands that may beused duringtheconversation. Thecommandsall begin with an escape character, 
initially " (tilde). The escape character isonly recognized at thebeginningof a line. To send an escape character to the 
remote system at the start of a line, it must beentered twice. Ali commands are either a single character or a word beginning 
with % (percent sign). 

cu recognizes thefollowi ng commands: 

Termi nate the conversation. 
"i command Run command ina shell. If command isempty, startsup a shell. 

"$ command Run comma nd , sending the standard output to the remote system. 

"I command Run c o mma n d , taki ng the standard input from the remote system. 

"+ command Run c o mma n d , taki ng the standard input from the remote system and sending the standard 

output to the remote system. 
"#, "%b r e a k Send a break signal, if possible. 

"c di rectory, "%cd di rectory C hangethe locai directory. 

"> file Send afileto the remote system. This just dumpsthefileover thecommunication line It is 

assumed that the remote system is expecting it. 
"< Receiveafilefrom the remote system. This promptsfor the locai filmarne and forthe 

remote command to executeto begin the fi le transfer. It conti nuesaccepting data until the 

contents of the eof read vari abl e are seen . 



cu 



"p from to, "%put troni to 

"t from to, "%take from to 

"s vari a b t e va! u e 
" ! vari a b ì e 
"z 

"%nostop 
"%stop 



escape 
delay 

eoi 

Pinary 

pinary-pref ix 

echo-check 

echonl 
timeout 

km 

resend 
eofwrite 
eof read 

verbose 



Send a fileto a remoteU N IX system. Thisrunstheappropriatecommandson theremote 
system. 

Retri ève a fi le from a remote U N IX system. Thisruns the appropriate commandson the 
remote system. 

Set a cu variableto thegiven vai ne. If vai ue isnot given, thevariableisset to True. 
Set a cu variableto False. 

Suspend thecu session. Thisisonly supported on somesystems. On systemsforwhich - z 

may beused to suspend ajob, ""z will also suspend thesession. 

Turn off xon/xoff handling. 

Turn on xon/xoff handling. 

Listali thevariablesand their values. 

Listali commands. 

cu also supports several variables. They may belisted with the~v command, and setwith the 

"s or "! commands. 

The escape character. I n i ti al ly - (tilde). 

If thi svari ableis True, cu will delay for asecond after recognizing the escape character before 
printing the nameof the locai system. The default isTrue. 

The list of characterswhich are considered to finish a line. The escape character isonly 
recognized after oneof theseisseen. The default i s carri age return, "u, "c, "o, "d, "s, "q, "r. 
W hether to transfer binary data when sending a file. If thisis False, then newl i nes i n the fi le 
being sent areconverted to carri age returns. The default is False. 
A stringused before sending a binary character in a fi le transfer, if the binary variableis 
True. The default is ~z. 

W hether to check filetransfers by examining what the remote system echoes back. This 
probably doesn't work very well . T he default is False. 

T he character to look for after sending each line in a file The default is carri age return. 
Thetimeoutto use, in seconds, when looking for a character, eitherwhen doingecho 
checkingorwhen I ooking for the echom character. The default is 30. 
T he character to useto delete a line if the echo check fai Is. The default is'u. 
Thenumber of ti mesto resend a lineif the echo check continuesto fai I. The default is 10. 
Thestringto write after sending a file with the "> command. The default is "d. 
Thestringto look for when receivingafilewith the '< command. The default is$, which is 
intended to beatypical shell prompt. 

W hether to print accumulate^ informati on duri ng a file transfer. The default isTrue. 



OPTIONS 

T he followi ng opti ons may be given to cu: 

-e, -parity=even 
-0, — parity=odd 
— parity=none 
-h, — half duplex 
-z system, —system system 
-c phone - number , — pilone phone - number 
-p port, -port port 
-a port 

-1 line, — line line 



Useeven parity. 
Useodd parity. 

U se no parity. N 0 parity is also used if both -e and -0 are given. 
Echo characters locai ly (half-duplex mode). 
Thesystem to cali. 
T he phone number to cali. 
Name the port to use. 
Equivalentto -port port . 

N amethelineto useby gi vi ng a devi ce name. This may beused to di al out on 
ports that are not listaci in theUU CP configuration files. Write access to thedevice 
is required. 



n 
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-s s p e e d , -speed s peed 
-# 

-n, -prompt 
-d 

-x type, -debug type 



-I file, — conf ig file 

-v, — version 
— help 



The speed (baud rate) to use. 

Where# isanumber, equivalentto -speed #. 

Prompt for the phonenumberto use. 

Enter debugging mode. Equivalentto -debug ali. 

Turn on parti cular debugging types. Thefollowing types are recognized: abnormai, 

chat, handshake, uucpproto, proto, pcrt, ccnfig, spooldir, execute, incoming, 
outgoing. 0 nly abnormai, chat, handshake, port, conf ig, incoming and outgoing are 

meaningful for cu. M ulti pie types may begiven, separated by commas, and the - 
debug option may appear multi pi e ti mes. A number may also begiven, which will 
turn on that many types from theforegoing list; for example, -debug 2 is 
equivalentto -debug abnormai, chat, -debug ali may be used to turn on ali 
debugging options. 

Set configuration fileto use This option may not beavailable, dependi ng upon 

how cu wascompiled. 

Report version information and exit. 

Print a help message and exit. 



BUGS 

This program doesnotwork very wdl. 
FILES 

The filmarne may bechanged at compilation ti me so thisisonly an approximation. Configuration file 

/usr/lib/uucp/config 

AUTHOR 

lan LanceTaylor (ian@airs.com) 



Taylor UUCP 1.05 
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cut— Remove sectionsfrom each lineof files 
SYNOPSIS 

cut {-b by t e - 1 i s t , — bytes=by t e-list} [-n] [ — help] [ — version] [file...] 

cut {-c character - 1 i st , — characters=c ha r act er ■ I i s t } [—help] [—version] [file...] 

cut {-f field-list, — fields=f i el d- 1 i st } [-d delitti] [-s] [ — delimiter=de I ì m] 
[ -only-delimited] [-help] [-version] [file...] 

D ESC RIFIO N 

Thismanual page documents the GN U version of cut. cut printssectionsof each lineof each input file, or the standard 
input if no files are given. A filenameof - means standard input. Thesectionsto beprinted areselected by the options. 

OPTIONS 

The byte- 1 i st , character - 1 i st , and f ì ei d - 1 i st options are one or more numbers or ranges (two numbers separated by a 
dash) separated by commas. Thefirst byte, character, and field arenumbered 1. Incomplete ranges may begiven: -m means 1- 
m; n- means n through end of li ne or last field. 



-b, -bytes byte- 1 i st 

-c, -cbaracters character-l i st 

-f , -fields f i el d- 1 i st 
-d, — delimiter del i m 
-n 

-s, — only-delimited 
— help 
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Print only the bytes in positions listaci in byte - 1 i st . Tabsand backspaces are treated like 
any other character; they take up one byte 

Print only characters in positions listed in charact er- 1 i st . Thesameas-b for now, but 
internationalization will changethat. Tabsand backspaces are treated like any other 
character; they take up one character. 

Print only the fields listed in f i ei d - m st . Fields are separated by tab by default. 

For -f, fields are separated by the first character in dei i m instead of by tab. 

Do not split multi byte characters (no -op for now). 

For -f, do not print li nesthat do not contain thefield separator character. 

Print ausagemessageand exit with a nonzero status. 

Print versi on informati on on standard output then exit. 

GNU TextUtilities 
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cvs— C oncurrent Versions System 
SYNOPSIS 

cvs [ cvs__options ] cvs-command [ command_options ] [command_args ] 

D ESC RIFIO N 

cvs is a front end to the rcs(l) revision control system, which extendsthenotion of revision control from acollection of files 
in a single directory to a hierarchical collection of di rectories consisti ng of revision controlied files. These di rectories and files 
can becombinedtogetherto forni a software rei ease. cvs providesthefunctionsnecessaryto manage these software releases 
and to control theconcurrent editing ofsource files among multiple software developers. 

cvs keeps a single copy of the master sources. T hi s copy iscalled thesourcerepository; it contai ns ali theinformation to 
permit extracting previ ous software releases at any timebased on either a symbolic revision tag, or a date in thepast. 

ESSENTIALCOMMANDS 

cvs providesa rich variety of commands(cvs_command in theSynopsis), each of which often hasawealth of options, to satisfy 
themany needs of source management in distributed environments. H owever, you don't haveto master every detail to do 
useful work with cvs; in fact, fivecommandsaresufficient to use (and contri buteto) thesourcerepository. 

cvs checkout moduies... A necessary prelimi nary for most cvs work: creates your private copy of the sourcefor 

modules (named collections ofsource; you can also use a path relative to thesource 
repository here). You can work with thiscopy without interferi ng with others' work. At 
least one subdirectory level isalwayscreated. 

cvs update Executethis com mand from within your private source directory when you wish to 

update your copies of source files from changes that other developers have made to the 
source in the repository. 

cvs add file... Usethis command to enroll new files in cvs records of your working directory. Thefiles 

will beadded to the repository thenext ti me you run cvs commit. N ote: You should use 
the cvs import command to bootstrap new sources into thesourcerepository. cvs add is 
only used for new files to an al ready checked-out module. 

cvs remove file... U se this command (after erasi ng any files listed) to declare that you wish to eli minate 

files from the repository. The removal does not affect others until you run cvs commit. 

cvs commit file... U se this command when you wish to "publish" your changesto other developers by 

incorporatingthem in thesourcerepository. 
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OPTIONS 

The cvs command linecan include cvs_optìons, which apply to the overall cvs program; a cvs_command, which specifies a 

parti Cular action on thesource reposi tory; and command_options and command_arguments tO fully speci fy what thecvs_command 

will do. 



WARNING 



You must becareful of precisely whereyou placeoptionsrelativetothecvs_command.Thesameoption can mean different 
things dependi ng on whether it isin thecvs_options position (to theleft of a cvs command) or in thecommand_options 
position (to the right of a cvs command). 



T nere are only two si tuations whereyou may omit cvs_command: cvs -h or cvs -heip elicitsa list of available commands, and 
cvs -v or cvs -version displays version information on cvs itself. 

CVS OPTIONS 

Asof rdeasel.6, cvs supportsGNU style long optionsaswell as short options. Only a few long opti ons are currently 
supported; these are listed in brackets after theshortoptionswhosefunctionsthey duplicate. 

U se these options to control the overall cvs program: 

-h [-heip] D isplay usage information about the specified cvs command (but do not actually executethe 

command). If you don'tspecify a command name, cvs -h displays a summary orali the 
commands available. 

-q Causes the command to bereally qui et; the command will generate output only for serious 

problems. 

-q Causes the command to besomewhatquiet; informational messages, such asreportsof 

recursion through subdirectories, aresuppressed. 
-b bindir Usebindir as the directory where RC S programsare located. 0 verrides the setting of the rcsbin 

environment variable. Thisvalueshould be specified asan absolute pathname. 
-d cvs_root_di rectory U se cvs_ r oot _ d i rectory as the root di rectory pathname of the master RC S source repository. 

0 verrides the setting of thecvs-RooT environment variable. Thisvalueshould be specified asan 

absolute pathname. 

-e editor Useeditor to enter revision log information. 0 verrides the setting of the cvseditor and the 

editor environmentvariables. 
-f Do not read the cvs startup file {" / . cvsrc). 

-ì Do not logthecvs_command in the command history (but executeit anyway). Seethedescrip- 

tion of the history command for information on command history. 

-n Do not change any t iies. Attempt to execute the cvs_command, but only to issue reports; do 

not remove update, or mergeany existingfiles, or create any new fi les. 

-t Trace program execution; display messages showing the stepsof cvs activity. P arti cui ari y useful 

with -n to explorethepotential impact of an unfamiliar command. 

-r M akes new working fi les read-only. Sameeffect asif the cvs -read environment variable is set. 

-v [-version] D isplays version and copyright information for cvs. 

-w M akes new working fi les read-wri te (default). 0 verrides the setting of the cvsread environment 

variable. 

-z compressi on- evei When transferring files across the network use gzip with compression level compressi on-i evei to 
compress and decom press data as it is transferred. Requi res the presence of the G N U gzip 
program in thecurrent search path at both endsof the link. 
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USAGE 

Exceptwhen requesti ng general helpwithcvs -h, you must specify a cvs_command to cvs to select a specific release control 
function to perform. Each cvs command accepts itsown collection of opti ons and arguments. H owever, many opti ons are 
available across several commands. You can display a usagesummaryfor each command by specifying the -h option with the 
command. 

CVS STARTUP FILE 

N ormally, when cvs startsup, it readsthe .cvsrc filefrom thehomedirectory of the user reading it. Thisstartup procedure 
can beturned off with the -f flag. 

The .cvsrc filelistscvs commands with a list of arguments, one command per line. For example, thefollowing line in 

.cvsrc! 
diff -c 

will mean thatthecvs diff command will alwaysbe passed the-c option in addition to any other optionsthat are speci fi ed 
in the command li ne (in thiscase, itwill havetheeffect of produci ng context sensitive diffsfor al I executionsof cvs diff ). 

CVSCOMMAND SU M MARY 

Here are bri ef descriptionsof ali the cvs commands: 

add Add a new fi le or directory to the repository, pendi ng a cvs commit on thesamefile. Can only bedone 

from within sourcescreated by a previouscvs checkout invocation. Use cvs import to place whole new 
hierarchiesof sources under cvs control. (Does not directly affect repository; changes working 
directory.) 

admin Execute RC S control functionson the source repository. (Changes repository directly; usesworking 

directory without changing it.) 
checkout M ake a worki ng di rectory of source fi les for editi ng. (C reates or changes worki ng di rectory.) 

commit Applyto the source repository changes, additions, and deletionsfrom your working directory. 

(Changes repository.) 

diff Show differences between fi les in working directory and source repository, or between two revisionsin 

source repository. (D oes not change either repository or working directory.) 
export Prepare copies of a set of sourcefiles for shipment off site. D iffers from cvs checkout inthatnocvs 

adm i n i strati ve di recto ri es are created (and thereforecvs commit cannot beexecuted from adi rectory 

prepared with cvs export), and asymbolic tag must bespecified. (Does not change repository; creates 

directory similar to working directories). 
history Show reportson cvs commands that you or others haveexecuted on a parti cular fi le or directory in the 

source repository. (D oes not change repository or working di rectory.) H istory logs are kept only if 

enabled by creation of the$cvsR00T/cvsR0OT/history file; see cvs(5). 
import Incorporate a set of updatesfrom off-siteinto the source repository, asa"vendor branchi. " (Changes 

repository.) 

log D i splay RCS log information. (Does not change repository or working directory.) 

rdiff Prepare a collection of diffs as a patch file between two releases in the repository. (Does not change 

repository or worki ng di rectory.) 
release Cancel a cvs checkout, abandoning any changes. (Can delete working directory; no effect on 

repository.) 

remove Removefilesfrom the source repository, pendi ng a cvs commit on thesamefiles. (Does not directly 

affect repository; changes working directory.) 
rtag Explicitly specify a symbolic tag for particular revisionsof filesin the source repository. Seealsocvs 

tag. (C hanges repository directly; does not require or affect working directory.) 
status Show current status of fi les: latest versi on, version in working directory, whether working version has 

been edited and, optionally, symbolic tags in theRCSfile. (Does not change repository or working 

directory.) 
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tag Specify a symbolic tag for files in the repository. By default, tags the revisionsthat were last synchro- 

nized with your working directory. (Changes repository di recti y; uses working directory without 
changing it.) 

update B ring your working di rectory up to date with changes from the repository. M ergesareperformed 

automatically when possible; a warning is issued if manual resolution is required for conflicting 
changes. (Changes working directory; does not change repository.) 

COMMON COMMANDOPTIONS 

Thissection describesthe command_options that areavailableacrossseveral cvs commands. N ot ali commandssupport ali of 
these options; each option is only supported for commands where it makes sense. H owever, when a command has one of 
theseoptionsyou can count on the samemeaning for the option asin other commands. (Other command options, which 
arelisted with the individuai commands, may havedifferent meaningsfrom onecvs command to another.) 



WARNING 



Thehistory command isan exception; it supportsmany options that conflict even with these standard options. 



-d date Usethemost recent revision no laterthan date_spec (a single argument, date descri ption specifyinga 

date in thepast). A widevariety of date formats are supported by theunderlying RCSfacilities, similar 
to those descri bed in co(l), but not exactly thesame. Thedate_spec isinterpreted asbeing in the locai 
ti me zone, un lessa speci fic timezoneisspecified. Thespecification is "sticky" when you useit to make 
a private copy of asourcefile; that is, when you get a working fi le usi ng-D, cvs records the date you 
specified, so that further updates in thesame di rectory wi II use thesame date (unless you explicitly 
overrideit; see the descri ption of the update command). -d is avai lable with thecheckout, diff, history, 
export, rdiff, rtag, and update commands. Examples of valid date speci fi cations include the following: 

1 month ago 

2 hours ago 
400000 seconds ago 
last year 

last M onday 
yesterday 
afortnightago 
3/31/92 10:00:07 PST 
January 23, 1987 10:05pm 
22:00 GMT 

-t When you specify a parti cular date or tag to cvs commands, they normally ignore files that do not 

contai n the tag (or did not exist on the date) that you specified. Use the -f option if you want files 
retrieved even when thereisno match forthetagordate. (The most recent versi on isused in this 
situation.) -t is avai lable with these commands: checkout, export, rdiff, rtag, and update. 

-h H elp; descri be the options avai lable for this command. This is the only option supported forali cvs 

commands. 

-k kf i ag Alter the default RCS processing of keywords; ali the-k options descri bed in co(l) are avai lable. The -k 

option is available with theadd, checkout, diff, export, rdiff, and update commands. Your kf i ag 
specifi cation is "sticky" when you useitto create a private copy of asourcefile that is, when you use 
thisoption with thecheckout or update commands, cvs associ ates your selected kf i ag with thefile, and 
continuesto useitwith future update commandson thesame fi le unti I you specify otherwise 
Someof the more useful kf i agsare-ko and -kb (for binary files, only compati ble with RCS version 5.7 
or later), and -kv, which is useful for an export where you wish to retai n keyword informati on after an 
import at some other site. 
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-ì Locai; run only in current working directory, rather than recurri ngthrough subdirectories. Available 

with thefollowing COmmands: checkout, commit, diff, export, remove, rdiff, rtag, status, tag, and 
update. 



WARNING 



This isnotthesameastheoverall cvs -1 option, which you can specify to theleft of acvs command. 



-n Do not run any checkout/commit/tag/update program. (A program can be specified to run on each of 

theseactivities, in the modules database; thisoption bypasses it.) Available with thecheckout, commit, 
export, and rtag commands. 



WARNING 



This is notthesameastheoverall cvs -n option, which you can specify to theleft of acvs command. 



-r tag 



Prune (remove) directoriesthat areempty after being updated, on checkout, or update. N ormally, an 
empty directory (onethat isvoid of revision-controlied files) isleft alone. Specifying-p will cause these 
directoriesto besilently removed from your checked-out sources. This does not remove the directory 
from the reposi tory, only from your checked out copy. N otethat this option isimplied by the -r or -d 

OptionSOf checkout and export. 

Pipe the files retri eved from the repository to standard output, rather than writingthem in thecurrent 
directory. Available with thecheckout and update commands. 

Use the revision specified bythetag argument instead of the default head revision. Aswell asarbitrary 
tagsdefined with thetag or rtag command, two special tags are always available: head refersto the 
most recent version available in the repository, and base refersto the revision you last checked out into 
thecurrent working directory. Thetag specification is "sticky" when you use thisoption with cvs 
checkout or cvs update to makeyour own copy of afile cvs remembersthetag and continuesto useit 
on future update commands, until you specify otherwise. tag can beeither asymbolic or numeric tag, 
in RCS fashion. Specifyi ng the -q global option along with the -r command option isoften useful, to 
suppressthewarning messageswhen the RCS filedoes not contain the specified tag. -r isavailable 

with thecheckout, commit, diff, history, export, rdiff, rtag, and update COmmands. 



WARNING 



This isnotthesameastheoverall cvs -r option, which you can specify to theleft of acvs command. 



CVS COMMANDS 

H ere (finally) aredetailson ali the cvs commands and the options each accepts. Thesummary linesat the top of each 
command's description highlight three kinds of things: 

Special options are described in detail; common command options may appear only 
in thesummary line. 

Some cvs commands require a working directory to operate; somerequirea 
repository. Also, some commands change the repository, some change the working 
directory, and some change nothing. 

M any commands havesynonyms, which you may find easier to remember (ortype) 
than the pri nei pai name. 



Command 0 ptionsand Arguments 
Working D irectory, or Repository? 

Synonyms 
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■ add [-k k f I a g ] [ — m ' me s s a g e 1 ] files... 
Requires Repository, working directory 
Changes Working directory 
Synonym: new 

Use the add command to create a new fi le or directory in the RCS source repository. The files or d i recto ri es speci fi ed with 
add must already exist in the current directory (which must have been created with thecheckout command). To add awhole 
new directory hierarchyto the source repository (forexample, files received fra m a thi rd-party vendor), usethecvs import 
command instead. 

If theargument to cvs add refersto an immediate subdirectory, the directory is created at thecorrect place in the RCS source 
repository, and the necessary cvs administration files are created in your working directory. If the directory already existsin 
the source repository, cvs add stili creates the administration files i n your version of the directory. Thisallowsyou to use cvs 
add to add a parti cular directory to your private so urceseven if someone else created that directory after your checkout of the 
sources. You can do thefollowing: 

example% mkdir new_directory 
example% cvs add new_directory 
example% cvs update new_directory 

An alternate approach usingcvs update might be: 

example% cvs update -d new_directory 

(To add anyavailable new directoriesto yourworking directory, it'sprobably simplerto use cvs checkout or cvs update -d.) 

Theadded files are not placed in the RCS source repository until you use cvs commit to makethechangepermanent. Doing 
acvs add on afilethatwasremoved with thecvs remove command wi II resurrect the file, if no cvs commit command 
intervened. 

You will have the opportuni tyto specify a logging message, as usuai, when you use cvs commit to makethenew file 
permanent. If you'd liketo haveanother logging message associ ated with just creation of the file (for example, to describethe 
file'spurpose), you can specify itwith the-m message option to theadd command. 

The -k k f i a g option specifies the default way that this fi le will bechecked out. Thekf i ag argument isstored in the RCS file 
and can bechanged with cvs admin. Specifying -ko isuseful for checking in binariesthat shouldn't have the RCS id strings 
expanded. 

■ admin [rcs-options] files... 

Requires Repository, working directory 

Changes: Repository 
Synonym: rcs 

This is the cvs interface to assorted administrative RC S facilities, documented in rcs(l). cvs admin simply passesall its 
optionsand argumentsto thercs command; it does no filtering or other processing. This command doeswork recursively, 
however, so extremecareshould beused. 

■ checkout [options] modules... 

Requires Repository 
Changes Working directory 

Synonyms: co, get 

M ake a working directory contai ni ngcopiesof the source files specified by modules. You must executecvs checkout before 
usi ng most of the other cvs commands, sincemost of them operate on yourworking directory. 

modui es are either symbolic names[themselvesdefined asthemodulemoduies in the source repository; seecvs(5)] for some 
collection of source di recto ri es and files, or pathsto di rectories or files in the repository. 

D ependi ng on the modules you specify, checkout may recursively create di rectories and populatethem with the appropriate 
source files. You can then editthese source files at anytime(regardlessof whether other software developers are editi ngtheir 
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own copiesof thesources); update them to include new changesapplied by othersto thesource repository; or commityour 
work as a permanent change to the RC S repository. 

N otethat checkout isused to create di rectories. The top-I evel directory created isalwaysadded to the directory where 
checkout isinvoked, and usuai ly hasthesamenameasthespecified module. In the case of a modulealias, the created 
subdirectory may haveadifferent name, but you can besurethat it will bea subdirectory, and that checkout will show the 
relative path leading to each fileasit isextracted into your private work area (unless you speci fy the -a global option). 

Runningcvs checkout on a directory that was al ready built by a prior checkout isalso permitted, and hasthesameeffect as 
speci fying the -d option to the update command described later. 

The opti ons permitted with cvs checkout include the standard command options-p, -f, -k kfiag, -1, -n, -p, -r tag, and -d 
date. In addition to those, you can useseveral special command optionswith checkout, asdetailed in thefollowing para- 
graphs. 

Use the -a option to reset any sticky tags, dates, or -k opti ons. (If you get a working file using one of the -r, -d, or -k 
options, cvs remembersthecorrespondingtag, date, or ktiag and conti nues using it on future updates; use the -a option to 
makecvs forget these specificati ons, and retrieve the head version of the file). 

The-j branch option mergesthechangesmadebetween the resulting revision and the revision that it isbased on (for 
example, if the tag refersto a branch, cvs will mergeall changesmadein that branch into your working fi le). 

With two -j options, cvs will mergein thechangesbetween thetwo respective revisi ons. This can beused to "remove" a 
certain delta from your working file. 

In addition, each -j option can contain on optional date specification which, when used with branches, can limit the chosen 
revision to onewithin aspecific date. An optional date is speci fi ed by addi ng a colon (:) to the tag. An example might be 
what cvs import tdlsyou to do when you havejust imported sourcesthat haveconflictswith locai changes: 

example% cvs checkout -jTAGiyesterday -jTAG module 

Use the -n option with -d dir to avoid shortening module paths in your working directory. (N ormai ly, cvs shortens pathsas 
much as possi ble when you specify an expl i ci t target directory.) 

Use the -c option to copy the module fi le, sorted, to the standard output, instead of creati ng or modifying any files or 
directories in yourworking directory. 

Usethe-d dir option to createa directory called di r for theworking files, instead of using themodule name Unlessyou 
also use-N, the paths created under dir will beas short aspossi ble. 

Use the -s option to display per-module status information stored with the-s option within themodulesfile. 

■ commit [-lnR][-m ' logjnessage ] -f file][-r revision] [f il es ... ] 

Requires Working directory, repository 

Changes Repository 
Synonym: ci 

Use cvs commit when youwantto incorporate changesfrom your working source files into the general source repository. 

If you don't specify parti cular fi lesto commit, ali of the files in yourworking current directory areexamined. commit is 
careful to change in the repository only those files that you havereally changed. By default (or if you explicitly specify the -r 
option), filesin su bdi rectories are also examined and committed if they have changed; you can usethe-i option to limit 
commit tothecurrent directory only. Sometimesyou maywantto forceafileto be committed even though itisunchanged; 
this is achieved with the-t flag, which also hastheeffectof disabling recursion (you can turn it back on with -r, of course). 

commit verifies that the selected files are up-to-date with the current revisi ons in the source repository; it will notify you, and 
exitwithout committing, if any of the specified files must bemade current first with cvs update, commit doesnotcall the 
update command for you, but rather leaves that for you to do when thetimeisright. 

When ali iswell, an editor is invoked to allow you to enter a log message that will bewritten to one or morelogging 
programsand placed in the RCS source repository file You can instead specify the log message on the command li ne with 
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the-m option, thus suppressing the editor invocati on, or use the -f option to specify that the argument fi le contai ns the log 
message. 

The -r option can beused to commit to a particular symbolic or numeric revision within the RCS file. For example, to bring 
ali your filesup to the RCS revision 3.0 (includi ng thosethat haven't changed), you might use 

example% cvs commit -r3.0 

cvs will only allow you to commit to a revision that ison the mai n trunk (a revision with a single dot). H owever, you can 
also commit to a branch revision (onethat hasan even number of dots) with the -r option. To create a branch revision, one 
typically use the -b option of thertag ortag commands. Then, either checkout or update can beused to base your sourceson 
thenewly created branch. From that point on, ali commit changes made within these working sourceswill be automati cai ly 
added to a branch revision, thereby not perturbi ng mainlinedevelopment in any way. For example, if you had to create a 
patch to the 1.2 versi on of the product, even though the 2.0 version isalready under development, you might usethis 

example% cvs rtag -b -rFCS1_2 FCS1_2 Patch productjnodule 
example% cvs checkout -rFCS1_2_Patch product module 
example% ed product module 
[ [ hack away ] ] 
example% cvs commit 

Say you havebeen working on someextremely experi mental software, based on whatever revision you happened to checkout 
last week. If others in your group would liketo work on this software with you, but without disturbi ng mainlinedevelop- 
ment, you could commit your changeto a new branch. Others can then check out your experi mental stuff and utilize the full 
benefit of cvs confi ict resolution. The scenario might look li ke this: 

example% cvs tag -b EXPR1 
example% cvs update -rEXPRI 
[ [ hack away ] ] 
example% cvs commit 

Otherswould simply do cvs checkout -texpri what ève r _ modu i e to work with you on the experi mental change. 

■ diff [-kl] [resdi f f _ o p t i ons ] [[ -r revl | -D d a t e 1 ] [ -r r ev 2 | -D d a t e 2 ] ] [f il es . . . ] 
Requires: W orking directory, repository 

Changes: Nothing 

You can compare your working fi les with revisions in the source repository, with the cvs ditt command. If you don't specify 
a particular revision, your fi I es are compared with the revisions they were based on. You can also use the standard cvs 
command option -r to specify a particular revision to compare your fi les with. F i nal ly, if you use -r twice, you can see 
differences between two revisions in the repository. You can also specify -d optionsto ditt against a revision in thepast. The 
-r and -D opti ons can bemixed together with at mosttwo opti ons ever specified. 

See resdiff (1) for a list of other accepted options. 

If you don't specify any fi les, ditt will display differences for ali thosefilesin thecurrent directory (and itssubdirectories, 
unlessyou use the standard option -ì) that differ from thecorresponding revision in the source repository (that is, fi les that 
you have changed), or that differ from the revision specified. 

■ export [ -f INnQq ] - r r e v ] -D date [— d dir][— k kflag] mo d u I e . . . 

Requires: Repository 
Changes: Current directory 

Thiscommand isavariantof cvs checkout: useitwhen you wantacopy of the source formo dui e without the cvs administra- 
tivedirectories. For example, you might use cvs export to prepare source for shipment off-site. Thiscommand requires that 
you specify a date or tag (with -d or -r), so that you can counton reproduci ng the source you ship to others. 

Theonly nonstandard options are-d di r (write the source into directory di r ) and -n (don'tshorten module paths). These 
havethesamemeaningsasthesameoptionsin cvs checkout. 



CVS 




The-kv option isuseful when export isused. Thiscausesany RCS keywordsto beexpanded such that an import doneat 
some other site will not lose the keyword revision information. Otherkfi ag optionsmay beused with cvs export andare 
described in co(l). 

■ history [■ r epor t ] [-f I ags ] [-opt i ons args ][f i I es . . .] 

Requi res: T he fi le $cvsROOT/cvsRooT/history 

Changes: Nothing 

cvs keeps a history fi le that trackseach useof thecheckout, commit, rtag, update, and reiease commands. You can use cvs 
mstory to display this information in variousformats. 



WARNING 



cvs history uses-f, -ì, -n, and -p in ways that confi ict with the descriptions in "Common Command 0 ptions," earlier 
in thismanual page. 



Several opti ons (shown as [ - r e p o r 1 1 in the precedi ng bull eted code li ne) control what kind of report isgenerated: 

-c Report on each ti me commit wasused (that is, each timetherepository wasmodified). 

-m modui e Report on a particular module. (You can meaningfully use-m morethan onceon thecommand line.) 

-o Report on checked-out modules. 

-t Report on ali tags. 

-x type Extract a particular set of record typesxfrom the cvs history. Thetypesare indicated by single letters, 

whichyou mayspecify in combination. Certain commands have a single record type: check-out (type 
o), reiease (type f), and rtag (type t). 0 ne of four record types may result f rom an update: w, when the 
working copy of afileisdeleted duri ng update (becauseitwasgonefrom the repository); u, when a 
working fi le was copi ed from the repository; g, when a mergewas necessary and it succeeded; and c, 
when a mergewas necessary but collisions were detected (requiring manual merging). Finally, oneof 
three record types results from commit: m, when afilewasmodified; a, when a file is first added; and r, 
when afileisremoved. 

-e Everything (ali record types); equivalent to specifying-xMACFROGwuT. 

-z zone Usetimezonezone when outputting history records. Thezonenameu standsfor locai time; numeric 

offsets stand for hoursand minutesahead of UTC. For example, +0530 standsfor 5 hoursand 30 
minutesahead of (that is, east of) UTC. 

The opti ons shown as -f 1 ags constrain the report without requiring option arguments: 

-a Show data for ali users. (The default isto show dataonly for the user executing cvs history.) 

-1 Show last modification only. 

-w Showonlytherecordsformodificationsdonefromthesameworkingdirectorywherecvs history is 

executing. 

The opti ons shown as-opti ons args constrain the report based on an argument: 

-b str Show data back to a record contai ni ng the stri ng str in either the module name, thefilename, or the 

repository path. 
-d date Show data sincedat e . 

-p re posi tory Show data for a particular source reposi tory (you can specify several -p optionson the same command 
line). 

-r rev Show records referring to revisionssince the revision ortag named r e v appearsin individuai RCSfiles. 

Each RCS file issearched for the revision ortag. 
-t tag Show records si ncetagtag waslast added to the history file. This differs from the -r flag in that it 

readsonly the history file, not the RCSfiles, and ismuch faster. 
-u name Show recordsfor username. 
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■ import [—opti ons ] reposi tory vendortag rei easetag ... 

Requires Repository, source distri bution directory 

Changes Repository 

Use cvs import to incorporate an enti re source distribution from an outside source (forexample, a source vendor) intoyour 
source repository directory. You can usethiscommand both for initial creation of a repository, and forwholesaleupdatesto 
themoduleform the outside source. 

The repository argument gives a directory name(or a path to a directory) under the CVS root directory for repositories if 
thedirectory did not exist, import createsit. 

When you use import for updatesto source that has been modified in your source repository (si nce a pri or import), it will 
notifyyou of anyfilesthatconflictin thetwo branchesof development; use cvs checkout -j to reconcile the differences, as 
import instructsyou to do. 

By default, certain filenames are ignored during cvs import: names associated with CVS administration, or with other 
common source control systems; common names for patch files, objectfiles, archivefiles, and editor backup files; and other 
names that are usually artifactsof assorted Utilities. Currently, the default list of ignored files includes files matchingthese 
names: 

RCSLOG RCS SCCS 
CVS* cvslog.* 
tags TAGS 

.make. state . nse_depinf o 
" #* .#* , 

.old *.bak * . BAK *.orig *.rej .del-* 
.a *.o *.so *.Z *.elc *.ln core 

The outside source issaved in afirst-level RCS branch, by default 1.1.1. U pdatesareleavesof thisbranch; forexample, files 
from the first imported collection of source will be revision 1.1.1.1, then files from the first imported update will be revision 
1.1.1.2, and so on. 

At least threeargumentsarerequired. repository isneeded to identify the collection of source. vendortag isatagforthe 
enti re branch (for example, for 1 .1 .1). You must also specify at least one rei easetag to identify the files at the leavescreated 
each timeyou executecvs import. 

0 ne of the standard cvs command options is available: -m message. If you do not specify a logging messagewith -m, your 
editor is invoked (aswith commit) to allow you to enter one 

T here are three additional special options 

Use-d to specify that each file'stimeof last modification should beused forthecheckin date and ti me. 
Use-b branch to specify a first-level branch other than 1.1.1. 

Use-i name to specify filenames that should be ignored during import. You can usethisoption repeatedly. To avoid 
ignoringanyfilesatall (even those ignored by default), specify -1 !. 

■ log [-1] ri og- opti ons [files...] 

Requires: Repository, working directory 

Changes: Nothing 
Synonym: riog 

D i splay log information for f i 1 es . cvs log calls the RCS utility nog; ali the options described in nog(l) are available. 
Among the more useful nog options are -h to display only the header (includi ngtag definiti ons, but omitting most of the 
full log); -r to select logson particular revisionsor rangesof revisions; and -d to select parti cular datesor dateranges. See 
nog(l) for full explanations. This command isrecursiveby default, unlessthe-i option isspecified. 
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■ rdiff [-f I ags ] [-V vn ] [-r t j-D d [ -r 1 2 J -D d 2 ] ] modul es . . . 
Requires Repository 

Changes Nothing 
Synonym: patch 

Builds a Larry Wall format patch(l) filebetween two releases that can befed di rectly i nto the patch program to bringan old 
release up-to-date with thenew release. (Thisisoneof thefew cvs commands that operates di rectly from the repository and 
doesn't require a prior checkout.) Thediff output issentto the standard output device You can specify (usi ng the standard 
-r and -d options) any combination of oneortwo revisionsor dates. If only one revision or date is speci fi ed, the patch file 
reflectsdifferences between that revision or date and thecurrent head revisionsin the RC Sfila 

N otethat if the software release affected is contai ned in morethan one directory, then it may be necessary to specify the -p 
option to the patch command when patching the old sources, so that patch isableto find the fi les that arelocated in other 
di recto ri es. 

If you use the option -v vn, RCS keywordsareexpanded accordi ngto therulescurrent in RCS version vn (theexpansion 
format changed with RCS version 5). 

The standard option fi ags -f and -ì are avai labi e with this command. There are also several special options fi ags. 

If you use the -s option, no patch output isproduced. Instead, a summary of the changed oradded fi les between the two 
releases issentto the standard output device. This isuseful forfindingout, for example, which fi les have changed between 
two dates or revisions. 

If you use the -t option, adiff of the top two revisions issentto the standard output device. This is most useful for seeing 
whatthelastchangeto afilewas. 

If you use the -u option, the patch output uses the newerunidiff format for context diffs 

You can use-c to explicitly specify thediff -c form of context difts (which is the default), if you like 

■ release [-dQq] modules... 

Requires Working directory 

Changes W orking directory, history log 

This command ismeant to safely cancel theeffect of cvs checkout. Sincecvs doesn't lockfiles, it isn't stri ctly necessary to use 
this command. You can alwayssimply delete your working directory, if you like butyou risk losing changes you may have 
forgotten, and you leaveno trace in the cvs history file that you'veabandoned your checkout. 

Use cvs release to avoid these problems. T his command checksthat no uncommitted changes are present; that you are 
executing it from immediately above, or inside, a cvs working directory; and that the repository recorded for your files is the 
same as the repository defi ned in the module database. 

If ali these conditions are true, cvs release leaves a record of itsexecution (attesti ngto your intentionally abandoningyour 
checkout) in the cvs history log. 

You can use the -d flag to request that your working copiesof the source files bedeleted if the release succeeds. 

■ remove [-1R] [files...] 

Requires Working directory 

Changes Working directory 

Synonyms ™, deiete 

Use this command to declare that you wish to remove fi les from the source repository. Like most cvs commands, cvs remove 
works on fi les in your working directory, not di rectly on the repository. Asasafeguard, it also requires that you first erase the 
speci fi ed fi les from your working directory. 

The fi les are not actually removed until you apply your changes to the repository with commit; at that poi nt, thecorrespond- 
ing RCS files in the source repository are moved into theAttic directory (also within the source repository). 



Parti: U ser Commands 



Thiscommand is recursive by default, schedili ing ali physically removed filesthat it findsfor removal by thenext commit. Use 
the-i option to avoid thisrecursion, or just specify that actual filesthatyou wish remove to consider. 

■ rtag [-f alnRQq] [-b] [ -d ] [ -r t a g | -D date] symbol i e t a g mo d u I e s . . . 

Requires Repository 
Changes Repository 

Synonym: rfreeze 

You can use thiscommand to assign symbolic tagsto particular, explicitly specified source versi ons in the repository. cvs 
rtag works directly on therepository contents (and requires no priorcheckout). Use cvs tag instead, to base the selection of 
versi ons to tag on the contents of your working directory. 

In general, tags(often the symbolic namesof software di stributi ons) should not be removed, but the-d option isavailableas 
a meansto remove completely obsolete symbolic namesif necessary (as mightbe the case foran Alpha release, say). 

cvs rtag will not mo ve a tag that al ready exists. W ith the -f option, however, cvs rtag will relocateany instanceof 
symbolic_ tag that already exists on that fi le to thenew repository versions. Without the -f option, attemptingto use cvs 
rtag to apply a tag that already exists on that fi le will produce an errar message. 

The -b option makes the tag a branch tag, allowing concurrent, isolateci development. Thisis most useful for creati ng a patch 
to a previously released software distributi on. 

You can use the standard -r and -d opti ons to tagonly those filesthat already contai n a certain tag. Thismethod would be 
used to renarne a tag: tag only thefiles identified by the old tag, then delete the old tag, leaving thenew tag on exactly the 
samefilesastheold tag. 

rtag executes recursively by default, tagging ali subdirectoriesof modulesyou specify in theargument. You can restrict its 
operation to top-leve! d i recto ri esw ith the standard -1 option: or you can explicitly request recursion with -r. 

The modules database can specify a program to executewhenever a tag is specified; a typical useisto send electronic mail to 
agroup of interested parties. If you wantto bypass that program, use the standard -n option. 

Use the -a option to have rtag look in theAttic for removed filesthat contai n the specified tag. The tag is removed from 
thesefiles, which makes it convenientto reuse a symbolic tag as development conti nues (and filesget removed from the 
upeoming distri bution). 

■ status [-lRqQ] [-v] [f i I es . . . ] 

Requires Working directory, repository 

Changes: Nothing 

D isplay a brief report on thecurrent statusof fileswith respectto the source repository, including any sticky tags, dates, or-k 
options. (Sticky options will restrict how cvs update operatesuntil you reset them; seethedescription of cvs update -a.... 

You can also use thiscommand to anticipate the potenti al impact of a cvs update on your working source directory. If you 
do not specify any fi les explicitly, reportsareshown forali filesthat cvs hasplaced in your working directory. You can limit 
thescopeof thissearch to thecurrent directory itself (not its subdi rectories) with the standard -1 option flag; oryou can 
explicitly request recursive status reports with the-R option. 

The-v option causesthesymbolic tagsfor the RC S fileto bedisplayed aswell. 

■ tag [-lQqR][-F][-b][-d][-r tag | -D date][-f] symbolic_tag [files ...] 
Requires Working directory, repository 

Changes Repository 
Synonym: freeze 

Use thiscommand to assign symbolic tagsto thenearest repository versions to your working sources. The tags are applied 
immediately to therepository, aswith rtag. 0 ne use for tags isto record a "snapshot" of thecurrent sources when the 
software freeze date of a project arrives. Asbugsarefixed after the freeze date, only those changed sources that areto be part 
of the release need be retagged. 
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Thesymbolic tags aremeantto permanently record which revisionsof which fileswere used in creati ng a software di stri bu- 
tion. Thecheckout, export, and update commands allow you to extract an exact copy of atagged releaseat any timein the 
future regardlessof whetherfileshavebeen changed, added, orremoved sincethereleasewastagged. 

You can use the standard -r and -d optionsto tagonly those fi lesthat al ready contai n a certain tag. Thismethod would be 
used to renarne a tag: tag only the f i les identifi ed by the old tag, then delete the old tag, leaving thenew tag on exactly the 
samefilesastheold tag. 

Specifyingthe-f flag in additi on to the -r or -d flags wi II tag those fi les named on thecommand lineeven if they do not 
contain the old tag ordid not exist on thespecified date. 

By default (without a -r or -d flag), theversionsto betagged are supplied implicitly by thecvs recordsof your working fi les' 
history ratherthan applied explicitly. 

Ifyou use cvs tag -d symboiic tag the symbolic tag you specify is deleted i nstead of bei ng added. 



WARNING 



Bevery certain of your ground beforeyou delete a tag; doing this effectivdy discardssome historical information, which 
may later turn out to have been valuable. 

cvs tag will not movea tag that already exists. With the -f option, however, cvs tag will relocate any instance of symbolic 
tag that al ready existson that fi le to thenew repository versions. Without the -f option, attemptingto use cvs tag to apply a 
tag that already exists on that fi le will produce an errar message. 

The -b option makesthetaga branch tag, allowingconcurrent, isolated development. Thisismost useful for creati ng a patch 
to a previously released software distributi on. 

N ormally, tag executesrecursively through subdirectories; you can prevent thisby usi ng the standard -1 option, or specify 
therecursion explicitly byusing-R. 

■ update [-Adf IPpQqR] [-d] [-r tag |-D date] fi I es ... 

Requires: Repository, working directory 

Changes; Working directory 

After you'verun checkout to create your private copy of sourcefrom the common repository, other deve! opers will continue 
changing the centrai source From timeto ti me when it isconvenient in your development process, you can use the update 
command from within your working directory to reconci le your work with any revisions applied to the source repository 
sinceyour last checkout or update. 

update keepsyou informed of its progress by printing a li ne for each file, prefaced with oneof thecharactersu, a, r, m, c, or ? 
to i ndicate the status of thefile: 

utile Thefilewasbroughtup-to-datewith respect to the repository. This isdonefor any file that exists in 

the repository but not in your source and for fi les that you haven't changed but are not the most 

recent versions available in the repository. 
a t i i e The fi le has been added to your private copy of thesources, and will be added to the RCS source 

repository when you run cvs commit on thefile. Thisisa reminder to you that the file needsto be 

committed. 

r t i i e Thefile has been removed from your private copy of thesources, and will beremoved from the RCS 

source repository when you run cvs commit on thefile. Thisisa reminder to you that the file needsto 
be committed. 

m t i i e Thefile ismodified in your working directory, m can indicate oneof two statesfor a fileyou're working 

on: either therewereno modificationsto the same fi le in the repository, so that your fi le remai nsas 
you last saw it; orthereweremodificationsin the repository aswell asin your copy, but they were 
merged successfully, without conflict, in your working directory. 
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c f i i e A conflictwasdetected whiletryingto mergeyour changesto f i i e with changesfrom thesource 

repository. file (the copy in your working directory) isnow the output of thercsmerge(l) command 
on thetwo versi ons; an unmodified copy of your fi lei salso in your working directory, with thename 
.#fiie.version, where version isthe RC S revision that your modified fi le started from. (N otethat 
some systems automati cally purgefilesthat begin with .# if they havenot been accessed for a few days. 
If you intend to keep a copy of your originai file, it isa very good ideato renarne it.) 

? f m e fi i e is in your working directory, but doesnot correspond to anything in thesource repository, and is 

notin the list of filesfor cvs to ignore; seethedescription of the-i option. 

Use the -a option to reset any sticky tags, dates, or-k options. (If you get a working copy of afileby using oneof the -r, -d, 
or-k options, cvs remembersthecorresponding tag, date, or ktiag and conti nues using it on future updates; use the -a 
option to makecvs forget thesespecifications, and retri ève the head version of the fi le). 

The-jbranch option merges the changes made between the resulti ng revision and the revision that it is based on. (For 
example, if the tag refersto a branch, cvs will mergeall changes made in that branch into your working fi le.) 

With two -j options, cvs will merge in the changes between thetwo respective revisi ons. Thiscan beused to "remove" a 
certain delta from your working fi le. For example, if the fi le foce is based on revision 1.6 and I want to remove the changes 
made between 1.3 and 1.5, 1 might do this: 

example% cvs update - j 1 . 5 -j1.3 foo.c # note the order... 

In addition, each -j option can contain on optional date specification which, when used with branches, can limit the chosen 
revision to onewithin aspecific date An optional date is speci fi ed by addi ng a colon (:) to the tag: 

-jSymbolic Tag:Date Specifier 

Use the -d option to create any directories that exist in the repository if they're missi ng from the working directory. 
(N ormally, update actsonly on directories and fi lesthat were already enrolled in your working directory.) This isuseful for 
updating directories that werecreated in the repository si nce the ini tial checkout; but it hasan u nfortu nate side effect. If you 
deliberately avoided certain directories in the reposi tory when you created your working directory (either through useof a 
modulenameor by listing explicitly thefilesand directories you wanted on the command line), then updating with -d will 
create those directories, which may not bewhat you want. 

Use-i name to ignore fi les whose names match n a me (in your working directory) duringtheupdate. You can specify-i more 
than onceon thecommand lineto specify several filesto ignore. By default, update ignores fi les whose names match any of 
thefollowing: 

RCSLOG RCS SCCS 
CVS* cvslog.* 
tags TAGS 

.make. state .nse_depinfo 
" #* .#* , 

.old *.bak * . BAK *.orig *.rej .del-* 
.a *.o *.so *.Z *.elc *.ln core 

Use-i! toavoid i gnori ng any fi les at al I. 

Thestandard cvs command options -f, -k, -1, -p, -p, and -r arealso available with update. 
FI LES 

For more detailed informati on on cvs supporting files, sea cvs(5). 
Filesin home directories: 

.cvsrc The cvs initialization file. Lines in thisfilecan beused to specify default optionsfor each cvs 

command. For example, the line diff -c will ensurethat cvs ditt isalwayspassed the-c option in 
addition to any other options passed on thecommand line. 

.cvswrappers Specifies wrappers to beused in addition to those speci fi ed in thecvsRooT/cvswrappers file in the 

repository. 



Files in working di rectories: 
cvs 

CVS/Entries 
CVS/Entrìes. Backup 
CVS/Entries. Static 
CVS/Root 



CVS/Repository 
CVS/Tag 

CVS/Checkin.prog 
CVS/Update. prog 

Files in source reposi tori es: 

SCVSROOT/CVSROOT 
CVSROOT/commitinfo.v 
CVSROOT/cvswrappers , v 



CVSROOT/editinfo.v 

CVSROOT/history 

CVSROOT/loginfo.v 

CVSROOT/modules.v 

CVSROOT/rcsinfo.v 

CVSROOT/taginfo.v 

MODULE/Attic 

#cvs.lock 

#cvs.tfl.pid 

#cvs.rfl.pid 

#cvs.wfl.pid 

ENVIRO NMENT VARIABLES 

CVSROOT 



CVSREAD 

RCSBIN 

CVSEDITOR 

CVS_IGNORE_REMOTE_ROOT 



CVS 




A directory of cvs adm ini strati ve files. Do not delete. 
List and status of fi les i n your working directory. 

A backup Of CVS/Entries. 

Flag: donotadd more entrieson cvs update. 

Pattinarne to therepository (cvsroot) location at the ti me of checkout. Thisfileisused instead 
of the cvsroot environmentvariableif theenvironment variableisnot set. A warning message 
will beissued when thecontentsof thisfileand thecvsRooT envi ronment variable differ. The 
fi le may be overri dden by the presence of thecvs_iGN0RE_REM0TE_R00T envi ronment vari able. 
Pathnameto thecorresponding directory in the source repository. 

Containstheper-directory sticky tag or dateinformation. Thisfileiscreated/updated when you 
specify -r or -d to the checkout or update commands, and no files are specifi ed. 
Nameof program to run on cvs commit. 
N ame of program to run on cvs update. 



D irectory of global administrativefilesfor repository. 
Recordsprogramsforfilteringcvs commit requests 

Recordscvs wrapper commandsto beused when checkingfilesinto and out of therepository. 

Wrappers allow the fi le or directory to beprocessed on theway in and out of cvs. Theintended 

usesaremany; one possi ble use would beto reformat a C file before thefile is checked in, so ali 

of the code i n the repository looks the same. 

Recordsprogramsforediting/validatingcvs commit logentries. 

Log file of cvs transactions. 

Records programsfor pipi ng cvs commit logentries. 

D efi nitions for modules in this repository. 

Records pathnamesto templatesused duri ng a cvs commit operation. 

Records programs for validating/logging cvs tag and cvs rtag operations. 

D i rectory for removed source fi les. 

A lock directory created by cvs when doing sensitive changesto the RCS source repository. 
Temporary lock filefor repository. 
A read lock. 
A write lock. 



Should contai n the full pathnameto theroot of the cvs source repository (where the RCS files 
are kept). This informati on must be avai lableto cvs for most commandsto execute; if cvsroot 
is not set, or if you wish to overrideit for one invocati on, you can supply it on thecommand 
line cvs -d cvsroot cvs command. ... You may not need to set cvsroot if your cvs binary has the 
right path compiled in; usecvs -v to display ali compiled-in paths. 
If this is set, checkout and update will try hard to makethefiles in your working directory read- 
only. W hen this is not set, the default behavior isto permit modification of your working files. 
Specifi es the full path name where to find RCS programs, such asco(l)and ci(l). If not set, a 
compiled-in valueisused; seethedisplay from cvs -v. 

Specifi es the program to use for recordi ng log messagesduring commit. If not set, the editor 
envi ronment variable isused instead. If editor isnot set either, the default is/usr/ucb/vi. 
If this variable is set, then cvs will ignoreall referencesto remote repositories in thecvs/Root 
file. 
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CVS_RSH 

CVS_SERVER 

CVSWRAPPERS 



AUTHORS 

D ick Grune 

Brian Berlina" 
J eff Polk 

SEEALSO 

ci(l), co(l), cvs(5), cvsbug(8), diff(l), grep(l), patch(l), rcs(l), rcsdiff(l), rcsmerge(l), rlogbug(8) 

13 M ardi 1996 

date 

date— Show and set date and time 
SYNOPSIS 

date [ -u ][-c ][-n ][-d dsttype ] [ -t mi nut es- west ] [ -a [ + |-]sss.fff ] [ +f o r ma t ][ 
[yyyy ]mmddhhmm[yy ] [. ss ] ] 

DESCRIPTION 

Datewithout argumentswrites the date and timeto the standard output in theform: 

Wed Mar 8 14:54:40 EST 1989 

with est replaced by the locai timezone'sabbreviation (or by the abbrevi ation forthetimezonespecified in theTz environ- 
ment variable if set). T he exact output format depends on the locale. 

If acommand-lineargument starts with a plussign (+), therest of theargument isused as a format that controlswhat 
appears in the output. In the format, when a percent sign (%) appears, itand the character after it arenot output, but rather 
identify part of the date or timeto be output in aparticular way (or identify a special character to output): 



Argument 


Sampleoutput 


Explanati on 


%a 


Wed 


Abbreviated weekday name* 


%A 


Wednesday 


Full weekday name* 


%b 


Mar 


Abbreviated month name* 


%B 


March 


Full month name* 


%c 


Wed Mar 08 14:54:40 198! 


) Date and time* 


%C 


19 


Century 


%d 


08 


D ay of month (always two digits) 


%D 


03/08/89 


M onth/day/year (eight characters) 



cvs uses the contentsof this variable to determinethe name of the remote shell command to use 
when startingacvs server. If this variable isnot set then rsr, isused. 
cvs uses the contentsof this variable to determi ne the name of the cvs server command. If this 
variable is not set then cvs is used. 

This variable isused by thecvswrappers script to determinethe name of the wrapper file, in 
addition to the wrappers defaults contai ned in the repository (cvsRooT/cvswrappers) and the 
user's home directory r/.cvswrappers). 



Originai authorof thecvssheii script version posted to comp.sources.unix in thevolume6 
releaseof D ecember, 1986. Credited with much of the cvs conflict resolution algorithms. 
Coder and designer of the cvs program itself in Aprii, 1989, based on the originai work doneby 
Dick. 

H elped Brian with the design of the cvs moduleand vendor branch support and authorof the 
checkin(l) shell script (the ancestor of cvs import). 



date 




Argument 


Sampleoutput 


Explanati on 


%e 


8 


D ay of month (leading zero blanked) 


%h 


Mar 


Abbreviated month name* 


%H 


14 


24-hour-clock hour (two digits) 


%I 


02 


12-hour-clock hour (two digits) 


%j 


067 


Julian day number (three digits) 


%k 


2 


12-hour-clock hour (leading zero blanked) 


%1 


14 


24-hour-clock hour (leading zero blanked) 


%m 


03 


M onth number (two digits) 


%M 


54 


M inute(two digits) 


%n 


nn 


N ewlinecharacter 


%p 


PM 


AM/PM designation 


%r 


02:54:40 PM 


H ounminutesecond AM /PM designation 


%R 


14:54 


H ounminute 


%S 


40 


Second (two digits) 


%t 


nt 


Tab character 


%T 


14:54:40 


H ounminutesecond 


%U 


10 


Sunday-based week number (two digits) 


%w 


3 


Day number (one digit, Sunday isO) 


%W 


10 


M onday-based week number (two digits) 


%x 


03/08/89 


Date* 


%X 


14:54:40 


Time* 


%y 


89 


Lasttwo digits of year 


%Y 


1989 


Year in full 


%Z 


EST 


Timezone abbrevi ation 


%+ 


Wed Mar 8 14:54:40 EST 198 


9 D efault output format* 


* T he exact output depends on the locale. 





If a character otherthan oneof thoseshown in the preceding table appears after apercent sign in the format, that following 
character is output. Ali other characters in the format are copi ed unchanged to the output; a newli ne character isalways 
added at the end of the output. 

In Sunday-based week numbering, the first Sunday of the year beginsweek 1; days preceding it arepart of week 0. In 
M onday-based week numbering, the first M onday of the year beginsweek 1. 

To set the date, use a command-l ine argument with oneof the following forms: 

1454 24-hour-clock hours (first two digits) and minutes 

081454 M onth day (first two digits), hours, and minutes 

0308H54 M onth (two digits, January isOl), month day, hours, minutes 

8903081454 Year, month, month day, hours, minutes 

0308H5489 M onth, month day, hours, minutes, year (on System V-compatiblesystems) 

030814541989 M onth, month day, hours, minutes, four-digityear 

198903081454 Four-digityear, month, month day, hours, minutes 
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If thecentury, year, month, or month day isnot given, thecurrent valueisused. Anyof the precedi ngformsmay be 
followed by a period and two digits that gi ve the seconds part of thenew ti me; if no seconds are given, zero isassumed. 

T hese options are available: 

-u or -c UseGMT when setti ng and showing the date and time. 

-n Do notnotifyothernetworked systemsof the time change. 

-d dsttype Set the kernel-stored D aylight SavingTimetype to thegiven value. (Thekernel-stored DST typeis 

used mostly by "old" binaries.) 

-t mi nutes- west Set the kernel-stored "minuteswest of GMT" value to the one given on thecommand line (The 

kernel-stored DST typeisused mostly by "old" binaries.) 

-a a d j u s t me n t Change the ti me forward (or backward) by thenumber of seconds (and fractionsthereof) specified 

in theadjustment argument. E ither the seconds part or thefractions part of theargument (but not 
both) may beomitted. On BSD-based systems, theadjustmentismadeby changing the rate at 
which timeadvances; on System-V-based systems, theadjustment ismadeby changing the ti me. 

FILES 

/usr/iib/iocaie/L/Lc time D escri ption of time locale l 

/usr/iocai/etc/zoneinfo T imezone i nformation directory 

/usr/local/etc/zoneinfo/localtime Locai timezonefile 
/usr/local/etc/zoneinfo/posixrules U Sed with PO SIX-StyleTZs 

/usr/local/etc/zoneinfo/GMT ForUTC leapseconds 

If /usr/local/etc/zoneinfo/GMT isabsent, UTC leap Seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 



dd 



dd- 



- Convert a file whi le copying it (data dumper) 



SYNOPSIS 

dd [-help] [-versioni [if=file] [of=file] [ ibs=b y t e s ] [obs=bytes] [ bs=b y t e s ] 
[ cbs=b y t e s ] [ skip=b I oc ks ] [ seek=b I ocks ] [count=bl oc ks ] [conv={ascii, 
ebcdic, ibm, block, unblock, lcase, ucase, swab, noerror, notrunc, sync}] 

D ESC RI PTION 

Thismanual page documents the GN U version of dd. dd copi es a fi le (from the standard inputto the standard output, by 
default) with auser-selectableblocksize, whi le optional ly performing conversi onson it. 

OPTIONS 

Numbers can be followed by a multiplier: 

b=512, c=1, k=1024, w=2, xm=number ni 

T hese options are available: 



— help 

— version 

if =f i I e 
of=f i I e 

ibs=b y t es 
obs=b y t es 
bs=by t es 



Printausagemessageon standard output and exitsuccessfully. 
Print version information on standard output then exitsuccessfully. 
Read from fi le i nstead of the standard input. 

Writeto fi lei nstead of the standard output. U nlessconv=notrunc is given, truncate 
fileto th e si ze speci fi ed by seek= (0 bytes if seek= isnot given). 
Read bytes bytes atatime. 
W ritebyt es bytes atatime. 

Read and write bytes bytes at a ti me. Overrideibs and obs. 
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cbs=b y t es 
skip=b I ocks 
seek=b I ocks 
count=b ocks 

conv=c o n v e r s i o n [ , c o n v e r s i o n . . . ] 

Conversions: 

ascii 

ebcdic 

ibm 

block 

unblock 

lcase 

ucase 

swab 

noerror 
notrunc 
sync 



depmod, modprobe 

depmod, modprobe— H andle loadable modules automati cally 
SYNOPSIS 

depmod [-a] 

depmod modulel.o rmo d u I e 2 . o ... 

modprobe module.o [symbol=val ne ...] 

modprobe -t t ag pattern 

modprobe -a -t tag pattern modprobe -1 [ -t tag ] pattern 

modprobe -r modul e 

modprobe -c 

D ESC RIFIO N 

These utilities are intended to makea Linux modular kernel manageable forali users, administrators, and distri bution 
maintainers. 

depmod creates a makefi le-li ke dependency file, based on the symbols it findsin the set of modules menti oned on the 
command li ne (or in a default place). This dependency file can later beused by modprobe to automatically load therelevant 
module(s). 

modprobe isused to load a set of modules— either a single module, astack of dependent modules, orali modul esthat are 
marked with aspecified tag. 

modprobe will automatically load ali base modules needed in a module stack, asdescribed by the dependency fi le modules. dep. 
If the loading of one of these modules fai Is, the whole current stack of modules wi II be unloaded (by rmmod) automatically. 

modprobe hastwo waysof loading modules. 0 ne way (the probe mode) will try to load a module out of a list (defined by 
pattern). It stops loading assoon as one module load successfully. This can beused to autoload one Ethernet driver out of a 
list, for example. Theother way isto load ali modul esfrom a list. This can beused to load some modules at boottime. 



Convertbytes bytesat atime. 

Skipbi ocks ibs-sized blocks at start of input. 

Skipbiocks obs-sized blocks at start of output. 

Copy only bi ocks ibs-sized input blocks 

C onvert the file as specified bytheconversion arguments. 

ConvertEBCDIC to ASCII. 
ConvertASCII to EBCDIC. 
ConvertASCII toalternateEBCDIC. 

Pad newline-terminated recordsto sizeof cbs, replacing newlinewith trailing spaces. 
R epl ace trai I i n g spaces i n cbs-sized block with newline. 
C hangeuppercasecharactersto lowercase. 
C hange lowercase characters to uppercase. 

Swap every pai r of input bytes. U nliketheU N IX dd, thisworkswhen an odd 

numberof bytes are read. If theinputfilecontainsan odd numberof bytes, thelast 

byte is si mply copied (sincethereis nothingto swap itwith). 

C onti nue after read errors. 

D o n ot tru n cate th e output fi I e. 

Pad every input block to sizeof ibs with trailing nulls. 

GNU Fi le U ti li ti es 
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With the opti on -r, modprobe will automati cally unload a stack of modules, similar to theway rmmod -r does. 

Option -ì combined with option -t listsall avai lable modules of a certain type. An enhanced mount command could use the 
command: 

modprobe -1 -t fs 

to get the list of ali fi le system driversavailableand on request load theproper one. So, themount command could become 
more generi c aswell. (Thekerneid solves this without changing the mount utility.) 

Option -c will printall configuration (default + confi guration file). 

Thenormal useof depmod isto include the line /sbin/depmod -a in one of the rc-mes in /etc/rc.d, so thatthecorrect 
moduledependencieswill be avai lable immediately after booti ng the system. 

Option -d puts depmod in debug mode. It outputsall commands it isissuing. 

Option -e outputs the list of unresolved symbol for each module, N ormally, depmod only outputs the list of unloadable 
modules. 

Option -v outputs the list of ali processed modules 

M odules may belocated at different place in thefilesystem, but there will always besomeneed to overridethis, especi al ly for 
module developers. Weexpect some officiai standard will emerge, defined by theFSSTN D. Until thattime, you might as 
well use this suggested directory structure 

CONFIGURATION 

Thebehaviorof depmod and modprobe can beadjusted by the (optional) configuration file /etc/cont .modules. 

The configuration file consists of a set of lines. Ali empty lines, and ali text on a line after a #, will beignored. Lines may be 
conti nued by ending the line with a \ . The remai ni ng lines should ali conform to oneof thefollowingformats: 

keep 

parameter=value 

options module symbol=value ... 
alias module real_name 
pre-instali module command ... 
instali module command ... 
post-install module command ... 
pre-remove module command ... 
remove module command . . . 
post-remove module command ... 

parameter=value options module symbol=value . . . alias module real_name 

Ali valuesin theparameter lines will be processed by ashell, which meansthat shell tricks like wildcards and commands 
enclosed in backquotes can beused: 

path[misc]=/lib/modules/1 . 1 .5?/misc 
path[net]=/lib/modules/ uname -r '/net 

Parametersmaybe repeated multipletimes. 
These are the legai parameters: 

depf iie=DEPFi le_path T his is the path to the dependency fi le that wi II becreated by depmod andused by modprobe. 
path=soME_PATH The patti parameter specifi es a directory to search for the modules. 

path[tag]=soME_PATH The patti parameter can carry an optional tag. This tei Is usa little more about the purposeof the 
modules in this directory and allows some auto mated operationsby modprobe. The tag isappended 
to the patti keyword enclosed in square brackets. If the tag ismissing, the tag mise isassumed. One 
very useful tag isboot, which can beused to mark ali modules that should beloaded at boottime 

If the configuration file /etc/cont .modules ismissing, or if any parameter isnot overridden, thefollowing defaults are 
assumed: 
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depf ile=/lib/modules/ 1 uname -r 1 /modules.dep 
patti [boot] = /lib/modules/boot 

path[fs]=/lib/modules/ 'uname -r 1 /fs 
path[misc]=/lib/modules/ ' uname -r 1 /mise 
patti] net ]=/ lib/modules/ 1 uname -r 1 /net 
path[scsi]=/lib/modules/ 1 uname -r 1 /scsi 

path[fs]=/lib/modules/def ault/f s 
path[ mise] =/lib/modules /default /mise 
pat ti [ net ]=/ lib/modules /default /net 
patti [ scsi] = /lib/modules /default /scsi 

path[fs]=/lib/modules/fs 
patti] mise ] = /lib/modules /mise 
patti] net ]=/lib/modules/net 
patti] scsi] = /lib/modules/scsi 

Ali option lines specify the default options that are needed foramodule, asin 

modprobe de620 bnc=1 

These options wi II beoverridden by any options given on the modprobe command line. 

T he al ias lines can beused to gi ve alias n amesto modules. A line in /etc/conf .modules that lookslikethis: 

alias iso9660 isofs 

makesit possi bleto write modprobe iso9660, although thereisno such moduleavailable. 
STRATEGY 

The idea is that modprobe wi 1 1 look first at the directory contai ni ng modules compi led forthecurrent releaseof the kernel. If 
themoduleisnotfound there, modprobe wi 1 1 look in the directory contai ni ng modules for a default release. 

When you instali a new Linux, the modules should bemoved to a directory related to the release (and version) of the kernel 
you are instali ing. Then you should do asymlink from this directory to the default directory. 

Each ti me you compi le a new kernel, the command make moduies_instaii will create a new directory, but won't changethe 
default. 

When you get a modul e un related to the kernel distri bution, you should place it in oneof theversion-independent 
d i recto ri es under /iib/moduies. 

Thisis the default strategy, which can beoverridden in /etc/conf .modules. 
EXAMPLES 

modprobe -t net Load one of the modules that are stored in the directory tagged net. Each module istried until one 

SUCCeedS. (Default: /lib/modules/net). 

modprobe -a -t boot Ali modules that are stored i n the directory tagged boot wi II be loaded. (D efault: /iib/moduies/ 
boot). 

modprobe siip.o Thiswill atterri pt to load the module sihc.o if it wasnot previously loaded, si nce the slip module 

needsthe functionality in thesihc module. Thisdependency will bedescribed in thefile 
modules.dep that was created automatically by depmod. 

modprobe -r siip.o Will unload siip.o. Itwill also unload sihc.o automatically, unlessit isused by someother module 
aswell (such asppp.o). 

FILES 

/etc/conf .modules 
/lib/modules/* /modules.dep 
/lib/modules/* 
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SEEALSO 

lsmod(l), kerneld(8), ksyms(l), modules(2) 

REQUIRED UTILITIES 

insmod(l), nm(l) rmmod(l) 

NOTES 

The pattern supplied to modprobe wi II often beescaped to ensurethat it isevaluated in theproper context. 
AUTHOR 

JacquesGelinas(]ack§solucorp.qc.ca), Bjom Ekwall (bj0rn@blox.se) 

BUGS 

N aah... 

Linux, 14 May 1995 
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df — Su m m ari ze f ree di sk space 
SYNOPSIS 

df [-aìkPv] [-tfstype] [-xfstype] [—ali] [ — inodes] [ — type=f s t y pe ] 
[ -exclude-type=f st y pe ] [ — kilobytes] [ — portability] [ — print-type] 
[-help] [-version] [f ilename . . . ] 

D ESC RIFIO N 

Thismanual page documents the GN U version of df. df displaystheamount of disk space availableon thefilesystem 
contai ningeach filenameargument. If no filmarne isgiven, the space availableon ali currently mounted filesystemsisshown. 
D isk space isshown in 1K blocks by default, unless the environment vari ableposixi_Y_coRRECT is set, in which case512-byte 
blocks are used. 

If an argument isthe absolute filenameof a disk device nodecontaining a mounted filesystem, df shows the space available 
on that filesystem rather than on thefilesystem contai ning the device node (which is always the root fi lesystem). This version 
of df cannot show the space availableon unmounted filesystems, becauseon most kindsof systemsdoingso requires very 
nonportable, intimate knowledgeof filesystem structures. 

OPTIONS 

-a, -ali Include in the I isti ng filesystems that haveO blocks, which areomitted by default. Such 

fi lesystems are typically special-purpose pseudo-filesystems, such asautomounter entri es. On 
some systems, filesystems of typeignore or auto arealso omitted by default and included in the 
listing by thisoption. 

■ i, -inodes List mode usage i nf ormati on instead of block usage An inode (short for "index node") isa 

special kind of disk block that contai ns information about a file, such asitsowner, permissions, 
timestamps, and location on thedisk. 

-k, -kilobytes P ri nt sizes in 1K blocks instead of 512-byte blocks. This overrides the environment variable 

POSIXLY_CORRECT. 

-p, - portability U se the posix output format. This is like the default format except that the information about 

each filesystem is always printed on exactly oneline; a mount device isnever put on a lineby 
itself. This means that if the mount device name is more than 20 characters long (asfor some 
network mounts), thecolumnsaremisaligned. 




-t, -print-type Print a type stringfor each fi lesystem. Any such printed filesystem typenamemay beused asan 

argument to either of the -type= or -exciude-type= options. 
-t, — type=f stype L imi t the listi ng to filesystemsof typef stype. M ulti pie fi lesystem typescan beshown by giving 

multiple -t options. By default, ali filesystem types are listed. 
-x, -exciude-type=f stype Limit the listi ng to fi lesystems not of type fstype. M ulti pi e f i I esystem typescan beeliminated by 

giving multi pie -x options. By default, ali filesystem types are listed. 
-v Ignored; for compati bility with System V versi onsofdf. 

-heip Printausagemessageon standard output and exitsuccessfully. 

-version Print version information on standard output then exitsuccessfully. 

GNU Fi le U ti liti es 
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dig— Send domain namequery packetsto nameservers 
SYNOPSIS 

dig [©server ] domain [<q uer y ■ t y pe >] [<q u e r y ■ c I as s >] [+<q ne r y ■ opt i o n >] [-<d i g- opt i o n >] 
[%c orarne ut ] 

DESCRIPTION 

dig (domain information groper) is a flexible command-linetool that can beused to gather information from the Domain 
N ame System servers. dig hastwo modes: si mpleinteractive mode that makes a single query, and batch that executes a query 
for each in a list of several query lines. Ali query options are accessi ble from thecommand line. 

The usuai simpleuse of dig takestheform: 

dig User ver domain query- type query- class 

where 

server M ay be either a domai n nameor adot-notation Internet address. If this optional field isomitted, 

dig will attempt to usethedefault nameserver foryour machine. 



NOTE 



If a domain nameisspecified, this will beresolved usi ng the domain name system resolver (bind). If your system doesnot 
support D N S, you may haveto specify a dot-notation address. Al ternati vely, if there is a server at your disposai some- 
where, ali that isrequired isthat /etc/resoiv.conf bepresentand indicatewherethedefault nameservers reside, so that 
server itself can beresolved. See resoiver(5) for information on /etc/resoiv.conf. 



WARNING 



Changing /etc/resoiv.conf will affect the standard resolver library and potenti al ly several programsthat use it.) Asan 
option, theuser may settheenvironmentvariableLocALREsto name a fi le whi eh isto beused instead of /etc/resoiv.conf 
(localres isspecifictothedig resolver and not referenced by thestandard resolver). I f the localres variable is not set or 
thefileisnot readable, then /etc/resoiv.conf will beused. 



d o ma i n 



The domain name for whi eh you are requesti ng information. See "Options" [-x] for aconvenient 
way to specify i nverse address query. 
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q u e r y - 1 y p e Thetypeof information (D N S query type) that you are requesti ng. If omitted, the default isa (t_a 

= address). T hefollowing types are recognized: 



Type 


Example 


D escripti on 


a 


T_A 


N etwork address 


any 


T_ANY 


All/any information about speci fi ed domain 


nix 


T_MX 


Mail exchangerfor the domain 


ns 


T_NS 


N ameservers 


soa 


T_SOA 


Zoneof authority record 


hìnf o 


T_HINFO 


H ost information 


axf r 


T_AXFR 


Zone transfer (must ask an auth ori tati ve server) 


txt 


T_TXT 


Arbitrary number of strings 



(SeeRFC 1035 for the complete list.) 

q u e r y - c i a s s T he network class requested in the query. I f omitted, the default is in (c_in = internet). The 

following classesare recognized: 

in c_in Internet class domain 

any c_any All/any class i nformation 

(SeeRFC 1035 for the complete list.) 



NOTE 



any can beused to specify a class and/or a type of query. dig will parse the first occurrenceof any to mean query -type = 

T_ANY. 

To specify query -class = c_any you must either specify any twice, or set query -class using-c option. (See"Other Op- 
ti ons," next.) 

0THER0PTI0NS 

%ignored-comment % isused to include an argumentthat issimply not parsed. Thismay beuseful if runningdig in 
batch mode. Instead of resolvi ngevery eserver -domai n- name in a list of queries, you can avoid the 
overhead of doingso, and stili havethedomain nameon thecommand lineasareference. 
Example: 

dig @128.9.0.32 %venera.isi.edu mx isi.edu 
-<dig opti o n > - isused to specify an option that affects the operati on of dig. The following options are currently 

available (although not guaranteed to be useful): 

-x dot - notati on - address C onvenient forni to specify inverse address mapping. Instead of 

dig 32.0.9.128.in-addr.arpa 

onecan simply use 
dig-x 128.9.0.32 

-t f i i e Fi le for dig batch mode. The fi le contai ns a list of query 

specifications(dig command lines) which areto beexecuted 
successively. Lines beginningwith ;, #, or \n areignored. Other 
options may stili appear on thecommand line, and will bein 
effect for each batch query. 

-t time Timein seconds between start of successive queries when running 

in batch mode. Can beused to keep two or more batch dig 
commands running roughly in sync. Default iszero. 



-p port 



-P[pi ng-string] 



-t query- type 



q u e r y - ci as s 



di g 



Port number. Query a name server I i sten i n g to a nonstandard port 
number. Default issa. 

After query returns, executea ping(8) command for responsetime 
comparison.Thisrather unelegantly makesa cali to theshell. The 
last three I ines of statisti cs is printed for the command: 
ping -sserver_name 56 3 

If theoptional ping string ispresent, itreplacesping -s in the 
shell command. 

Specify type of query. M ay speci fy either an i nteger value to be 
included in the type field or usetheabbreviated mnemonic as 
discussed earlier (mx = tjx). 

Specify class of query. M ay specify either an i nteger value to be 
included in the class field or usetheabbreviated mnemonicas 
discussed earlier (in = c_in). 
Thisflagspecifiesthatthedig environment (defaults, print options, and so on), after ali of the 
argumentsareparsed, should besaved to afileto become the default environment. Useful if you do 
not like the standard set of defaults and do not desi reto i nclude a large number of options each 
timedig isused. The environment consistsof resolver state variableflags, timeout, and retriesas 
well astheflagsdetailingdig output (see below). If theshell environment variablei_ocALDEF i s set to 
the name of a fi le, thisiswhere the default dig environment issaved. If not, thefile DiG.env is 
created in the current working directory. 



localdef isspecificto the dig resolver, and will notaffect operation of thestandard resolver library. 



Each timedig isexecuted, it looksfor ./DiG.env or the file specified by the shell environment 
vari abl e localdef. If such fileexi stsand isreadable, then the environment isrestored from thi sfile 
before any argumentsare parsed. 

-envset T his flag only affects batch query runs. When -envset is specified on a li ne in a dig batch file, the 

dig envi ronment after the arguments are parsed, becomes the default envi ronment for the duration 
of the batch file, or until thenext li ne which specifies -envset. 

-[nojstick T his flag only affects batch query runs. It specifies that the dig environment (asread i nitial ly or set 

by -envset switch) isto berestored before each query (line) in adig batch file Thedefault -nostick 
means that the dig envi ronment does not stick, nence options specified on a si ngle I ine in adig 
batch fi le will remai n in effectfor subsequent I ines (that is, they are not restored to thesticky 
default). 

+<q u e r y opti on> + isused to specify an option to bechanged in the query packet orto changedig output specifies. 

M any of thesearethesameparametersaccepted by nsiookup(8). If an option requiresa parameter, 

theform isasfollows: 

-fkeyword[=value] 

M ost keywords can be abbrevi ated. Parsing of the +options is very simplistic— a value must notbe 
separated from its keyword by whitespace. Thefollowing keywords are currently available: 

Keyword Abbreviation M eaning (D efault) 

[nojdebug (deb) Turn on/off debugging mode[deb] 

[no]d2 Turn on/off extra debugging mode [nod2] 

[nojrecurse (ree) U Se/don't US6 recursi ve lOOkup [ree] 

retry=# (ret) Set number of retri es to #[4] 



continues 
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Keyword Abbreviati on 


M eaning (Default) 


time=# (ti) 


Set timeout length to #seconds[4] 


[no]ko 


Keep open option (impliesvc) [noko] 


[no]vc 


Use/don't use virtual circuit [nove] 


[nojdefname (def) 


Use/don't use default domain name[det] 


[no]search (sea) 


Use/don't use domain search list [sea] 


domain=NAME (do) 


Set default domain nameto name 


[no]ignore (i) 


Ignore/don't ignoretrunc. errors[noi] 


[nojprimary (pr) 


U se/don't use primary server [nopr] 


[nojaaonly (aa) 


Authoritative query only flag [noaa] 


[nojsort (sor) 


Sort resource records[nosor] 


[no]cmd 


Echo parsed arguments[cmd] 


[nojstats (st) 


Print query stati stics [st] 


[no]Header (h) 


Print basic header [h] 


[nojheader (he) 


Print header flags [he] 


[nojttlid (tt) 


PrintTTLs[tt] 


[no]cl 


Print Class info [noci] 


[no]qr 


Print outgoing query [noqr] 


[no] reply (rep) 


Print reply [rep] 


[nojques (qu) 


Print question section [qu] 


[nojanswer (an) 


Print answer section [an] 


[nojauthor (au) 


Print authoritative section [au] 


[nojaddit (ad) 


Print additional section [ad] 


pfdef 


Set to default print flags 


pf min 


Set to minimal default print flags 


pfset=# 


Set print flags to # (# can behex/octal/decimal) 


pfand=# 


Bitwiseand print flags with # 


pfor=# 


Bitwiseor print flags with # 



The retry and une options affect the retransmission strategy used by resolver library when sending datagram queries. The 
algorithm isasfollows: 

August 30, 1990 

for i = 0 to retry - 1 

for j = 1 to num_servers 

send_query 

wait((time * (2**i)) / num_servers) 

end 

end 

Notethatdig alwaysusesavalueof 1 for num_servers. 
DETAILS 

dig oncerequired aslightly modified version of theBiND resolver (3) library, bind's resolver has(asof bind4.9) been 
augmented to work properly with dig. Essentially, dig isastraightforward (albeit not pretty) effort of parsi ng arguments and 
setting appropriate parameters. dig uses resolver routinesres_inito, res_mkqueryo, res_send<) aswell as accessi ng_res 
structure. 



dnsquery 



FILES 

/etc/resoiv.conf Initial domain name and name server addresses 

ENVIRONMENT 

LOCALRES filetO USe in placeof /etc/resoiv.conf 

localdef default environmentfile 
AUTHOR 

Steve HotZ (hotzWsi.edu) 

ACKNOWLEDGMENTS 

dig usesfunctionsfrom nsiookup(8) authored by Andrew Cherenson. 

BUGS 

dig has a serious case of "creeping featurism," the result of considering several potenti al uses duri ng its development. It would 
probably benefit from a rigorousdiet. Similarly, theprintflags and granularity of theitemsthey specify makeevidenttheir 
rather ad hoc genesi s. 

dig does not consistently exit nicely (with appropriate status) when a problem occurssomewherein the resolver (M ost of the 
common exit cases are handled.) This isparticularly annoying when running in batch mode. If it exits abnormally (and isnot 
caught), the enti re batch aborts; when such an event istrapped, dig si mply conti nues with the next query. 

SEEALSO 

named(8), resolver(3), resolver(5), nslookup(8) 

30 August 1990 

dnsquery 

dnsquery -Query domain name servers usi ng resolver 
SYNOPSIS 

dnsquery [-n nameserver] [-t type] [-c class] [-r retry] [-p retry period] 
[-d] [-s] [-v] h o s t 

D ESC RIFIO N 

The dnsquery program is a general interface to nameservers viaBiND resolver library cai I s. The program supportsqueriesto the 
nameserver with an opcodeof query. This program isintended to bea replacement or supplement to programslikenstest, 
nsquery, and nsiookup. Ali arguments except for nost and ns aretreated without case-sensitivity. 

OPTIONS 

-n The nameserver to be used i n the query. N ameservers can appear as either I nternet addresses of the form 

w. x. y. z or can appear as domain names. (default: asspecified in /etc/resoiv.conf) 
-t The type of resource record of interest. Types include: 



a Address 

ns N am eserver 

cname Canonical name 

ptr Domain name pointer 

soa Start ofauth ori ty 
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WKS 


Well-known service 


HINFO 


H ost information 


MINFO 


M ailbox information 


MX 


M ail exchange 


RP 


Responsibleperson 


MG 


M ail group man ber 


AFSDB 


DCE orAFSserver 


ANY 


Wildcard 



NOTE 



Any case may be used (the default ìsany) 

-c T he class ofresourcerecordsof interest. C lasses include the following: 

in Internet 
hs Hesiod 
chaos C haos 

any Wildcard 



NOTE 



Any case may be used (the default is in). 

-r Thenumberof timesto retry if the nam eserver isnot responding. (default: 4) 

-p Period to wait beforetiming out. (default: res_timeout) optionsfidd. (default: anyanswer) 

-d Turn on debugging. Thissets the res_debug bit of theresolver'soptions field. (default: no debugging) 

-s Useastream ratherthan a packet. ThisusesaTCP stream connection with the nameserver rather than a 

U D P datagram. ThissetstheREs_usEvc bit of theresolver'soptions field. (default: udp) 
-v Synonym forthes flag. 

host The nameof thehost(or domain) of interest. 

FILES 

/etc/resolv.conf 
<arpa/nameser . h> 
<resolv.h> 

SEEALSO 

nslookup(8), nstest(l), nsquery(l), named(8), resolver(5) 

DIAGNOSTICS 

If the resolver fai Isto answer thequery and debugging hasnot been turned on, dnsquery will simply print a messagelikethis: 

Query failed (re = 1) : Unknown host 

T he valueof the return codeissupplied by h_errno. 



To getthedefault ns and search lists. 
List of usableRRtypesand classes 
List of resolver fi ags 



dsplit 



BUGS 

Queriesof a class other than in can have interesting results si nce ordì nari ly a nameserver only hasa list of root nameservers 
for class in resource records. 

Query usesa cali to inet_addro to determi ne if the argument for the -n option isa valid Internet address. U nfortunately, 
inet_addr(> seemsto cause a segmentation fault with some(bad) addresses (for example, 1.2.3.4.5). 

AUTHOR 

Bryan Beecher 

10 M arch 1990 



domainname 

domainname— Set or print domain of current host 
SYNOPSIS 

domainname [ n a me ] 

DESCRIPTION 

domainname prints the domai n nameof the current host, from thegetdomainname(3) library cali. If an argument ispresentand 
theeffectiveUID isa, domainname changes the name of the host, with thesetdomainname(2) system cali. Thisisusually doneat 
boot timein the /etc/ re. locai script. 

FILES 

/etc/rc . locai 

SEEALSO 

getdomainname(3), setdomainname(2), uname(l), uname(2) 

AUTHOR 

LarsWirzenius by substituting in hostname.c 

Linux 0.98, 26 December 1992 



dsplit 

dspiit— Split a largefileinto pieces 
SYNOPSIS 

dsplit [ -size nnn ][i nput_fi I e [ output_base ]] 

DESCRIPTION 

dspiit spi i ts binary fi les i nto smaller chunks so that they may be placed on floppy disks. 
OPTIONS 

-size nnn Specifies the size of each output file, in bytes. The default is 1457000, which isenough to will a 

1.44M B floppy disk. 

i n p u t _ f i i e Specifi es the nameof the file to split up. A - indicates standard input. The default is standard 

input. 
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output. base Specifies the name of the output files to be written. dspiit will append 000, 001, . . ., to the 

out put. base. The default iSdsplit. 

AUTHOR'S NOTES 

Submitted by: D avid Arnstein (arnstein@netcom.coin) 
Posti ng number: Volume40, IssueSl 
Archivename: dspnt/part0i 
E nvironment: MS-DOS, UNIX 

H ere i s a portable binary fi le splitting program. It reads a binary fi le and splitsit into pieces. I use this program to put large 
binary files on floppy disks. Forthisreason, the default size of the output fi les is 1,457,000 bytes, which just aboutfillsup a 
1.44M B floppy disk. 

Unlikeother binary split programsl haveseen, dspiit doesnot maiioc ahugeblock of memory. dspiit issuitablefor use 
under M S-D OS and other p ri mi ti ve operati ng system s. 

(The program camefrom gatekeeper.dec.com: /pub/ usenet /comp.sources. mise /volume40/dsplit). 

Linux 1.1, 5 July 1994 



du 



du— Summarizedisk usage 
SYNOPSIS 

du [-abcklsxDLS] [-ali] [-total] [ -count-links] [ — summarize] [-bytes] 
[-kilobytes] [ -one-f ile-system] [ — separate-dirs] [ -deref erence] 
[ -dereference-args] [ — help] [--version] [fi I e n a me ... ] 

D ESC RIPTIO N 

Thismanual page documents the GN U version of du. du displaystheamount of disk space used by each argument and for 
each subdirectory of directory arguments.Thespaceismeasured in 1K blocksby default, unlesstheenvironment variable 
posixly_correct i s set, in which case 512-byte blocks are used. 



OPTIONS 

-a, -ali 
-b, -bytes 
-c, -total 

-k, -kilobytes 
-1, —count-links 
-s, —summarize 
-x, —one-f ile-system 

-D, —dereference-args 



-L, — dereference 

-S, -separate-dirs 
— help 



Displaycountsforall files, not just directories. 
Print sizes in bytes. 

Write a grand total ofall of thearguments after ali arguments havebeen processed. Thiscan 
beused to find out the disk usage of a directory, with somefilesexcluded. 
Print sizes in kilobytes. T hisoverrides the environment variable posixly_correct. 
Count the size ofall files, even if they haveappeared al ready in anotherhard link. 
Displayonlyatotal for each argument. 

Skip directories that areon different filesystemsfrom the onethat the argument bei ng 
processed ison. 

D eref eren cesymboliclinksthatarecommand-line argu m ents. D oes n ot affect oth er 
symbolic links This is hdpful for fi nding out the disk usage of directories li ke /usr/tmp 
where they are symbolic links 

D ereference symbolic links (show the disk space used by the fi le or directory that the link 
pointsto instead of the space used bythelink). 

C ount the size of each di recto ry separately, not i ncludi ng the sizes of subdi rectories. 
Print a usage messageon standard output and exit successfully. 
Print version informati on on standard output, then exit successfully. 



editres 




BUGS 

On BSD systems, du reports sizes that arehalf thecorrect valuesfor filesthat areN FS-mounted from H P-UX systems On 
HP-UX systems, it reports sizes that are twice thecorrect valuesfor filesthat areN FS-mounted from BSD systems. Thisis 
dueto aflaw in H P-UX; italso affects the H P-UX du program. 

GNU F i le U ti I i ti es 

editres 

editres— A dynamic resource editor forX Tool kit applications 
SYNTAX 

editres [ —tool ki topti on ... ] 

OPTIONS 

editres accepts al I of the standard X Toolkit com mand-l ine opti ons(seex(l)). The order of thecommand-lineoptionsisnot 
important. 

D ESC RIFIO N 

editres isatool that allows users and application developersto view the full widget hierarchy of any X Toolkit application 
that speaks the editres protocol. In addition, editres will help the user construct resource speci fi cations, allow the user to 
apply the resource to the application and view the results dynamically. 0 nce the user is happy with a resource speci fi cation, 
editres will append the resource stri ngto theuser'sX Resources file. 

USING editres 

editres provides a wi ndow consisti ng of the followi ng four areas: 

M enu Bar A set of pop-up menusthat allow you full access to editres'sfeatures. 

Panner The panner providesa more intuì ti ve way to scroll the application tree display. 

M essageArea D isplaysinformation to theuserabout the action that editres expects. 

Application Widget Tree Thisarea isused to display the selected appi ication's widget tree. 

To begin an editres session, sei ectth e G et Widget Tree menu item from theCommand menu. Thiswill change the pointer 
cursor to crosshair. You should now select the application you wish look at by clickingon any of its Windows. If this 
application understands the editres protocol, editres will display theapplication'swidgettreein its tree window. If the 
application doesnot understand the editres protocol, editres will inform you of this fact in the message area after a few 
secondsdelay. 

After you have a widget tree, you may select any of the other menu opti ons. The effect of each of theseisdescribed in 
"Commands," next. 

COMMANDS 

G et Widget Tree 

Refresh Current W idget Tree 



Allows the user to click on any application that speaks the editres protocol and receive its 
widget tree 

editres only knows about the widgets that exist at the present ti me. M any applications 
create and destroy widgets on thefly. Selecting this menu item will cause editres to ask the 
application to resend its widget tree, thusupdating its information to thenew state of the 
application. 

For example, xman only createsthewidgetsfor itstopboxwhen it startsup. N oneof the 
widgets for the manual page window arecreated until the user actually clickson theM anual 
Pagebutton. If you retrieved xman'swidget tree before the manual pageisactive, you may 
wish to refresh the widget tree after the manual pagehasbeen di splayed. Thiswill allow you 
to also edit the manual page's resources. 
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Dump WidgetT ree to a File 



Show ResourceBox 



Set Resource 



Quit 



W hen documenti ng appi icationsit isoften useful to beableto dump the enti re application 
widget tree to an ASC 1 1 file. Thisfilecan then beincluded inthemanual page. W hen this 
menu item isselected, a pop-up dialog isactivated. Typethenameof the fi le in thisdialog, 
and either select 0 kay, or type a carri age- return, editres will dump the widget tree to this 
file. To cancel the fi le dialog, select the Cancel button. 

Thiscommand will pop up a resource box for the current application. This resource box 
(described in detail later in thissection) will allow the user to seeexactly which resources 
can be set for the widget that iscurrently selected in the widget tree display. 0 nly one 
widget may becurrently selected; if greater or fewer are selected, editres will refuse to pop 
up the resource box and put an error messagein theM essageArea. 
Thiscommand will pop up asimpledialog box for setti ng an arbitrary resource on ali 
selected widgets. You must type in the resource name, aswell asthevalue. You can usethe 
Tab key to switch between the resource namefield and the resource value fi eld. 

ExitS editres. 



TREE COMMANDS 

The Tree menu contai nsseveral commands that enableoperationsto be performed on the widget tree. 



Select Widget in Client 



Select Ali, Unselect Ali, 
Invert Ali 
Select C hi Idren, 
Select Parents 
Select Descendants, 
Select Ancestors 
ShowWidgetNames, 
ShowClassNames, 
Show Widget Windows 



Flash Acti ve Widgets 



Thismenu item allowsyou to select any widget in theapplication; editres will then 
highlight the correspondingelement the widget tree display. After thismenu item is 
selected, the pointer cursorwill again turn to acrosshair, and you must click any pointer 
button in the widget you wish to havedisplayed. Si nce some widgets are fui ly obscured by 
their chi Idren, itisnot possi bleto get to every widget thisway, butthismechanism does 
givevery useful feedback between the elements in the widget tree and thosein theactual 
application. 

Thesefunctions allow the user to select, unselect, or invert ali widgets in the widget tree. 

T hesefunctions select the immediate parent or chi Idren of each of thecurrently selected 
widgets. 

Thesefunctions select ali parents or chi Idren of each of thecurrently selected widgets. This 
isarecursivesearch. 

W hen the tree widget isinitially displayed, the labelsof each widget in the tree correspond 
to thewidget names. Thesefunctionswill cause the label of ali widgets in the tree to be 
changed to show the class name, IDs, or window associated with each widget in the 
application. Thewidget IDs, and Windows areshown as hex numbers. 
In addition, therearekeyboard accelerators for each of the Tree operati ons. If theinput 
focus is over an individuai widget in the tree, then that operati on will only affect that 
widget. If the input focus is in theT ree background, itwill haveexactlythesameeffectas 
thecorresponding menu item. 

Thetranslation entri esshown may beapplied to any widget in theapplication. If that 
widget isachild oftheTree widget, then itwill only affect that widget; otherwise, itwill 
havethesameeffect as the commands in the Tree menu. 

Thiscommand istheinverseof the Select Widget in Client command; itwill show the user 
each widget that is currently selected in the widget tree by flashing the correspondi ng widget 
in theapplication numFiasr.es (threeby default) times in the flash -color. 



Key Option 

space Unselect 

w Select 

s Select 

i I nvert 



Translation Entry 
Select(nothing) 
Select(widget) 
Select(all) 
Sei ect( invert) 



editres 




Key 


0 pti on 


Translation Entry 


c 


Select 


Children Select(children) 


d 


Select D escendants 


Select(descendants) 


n 

r 


Select Parent 


Select( parent) 


a 


Select Ancestors 


Sei ect( ancestors) 


N 


Show W idget N ames 


Relabel (name) 


C 


Show C lass N ames 


Relabel (class) 


1 


Show W idget IDs 


Relabel(id) 


W 


Show W idget Windows 


Relabel(window) 


T 


Toggle W idget/C lass N ame 


Relabel(toggle) 



Clicking button 1 on awidget adds it to the set of selected widgets. Clicking button 2 on awidget deselectsall other widgets 
and then selectsjust that widget. Clicking button 3 on awidget togglesits label between the widget'sinstance name the 
widget's class name. 

USINGTHERESOURCEBOX 

The resource box containsfivedifferent areas. Each of theareas, asthey appear on thescreen from top to bottom, are 
discussed in thefollowing list: 

T he Resource Line T his area at the top of the resource box shows the current resource name exactiy as it 

would appear if you wereto saveit to a file or apply it. 

The Widget N ames and Classes T his area enables you to select exactiy whi eh widgets this resource wi II apply to. The 

area contai nsfour lines; the first contai ns the name of the selected widget and ali its 
ancestors, and themorerestrictivedot(.) separator. Thesecond li ne contai nsless 
specific class namesof each widget, aswell astheless restri cti ve star (*) separator. 
Thethird I ine contai ns a set of special buttons called AnyW idget that wi II general ize 
thislevel to match any widget. The last line contains a set of special buttons called 
Any Widget Chain that wi II turn the si ngle level into somethingthat matcheszero or 
more leve! s. 

Theinitial state of this area isthemost restri ctive, usi ng the resource names and the 
dot separator. By sei ecting the other buttonsin thisarea, you can ease the restri cti ons 
to allow more and more widgets to match the specificati on. The extreme case i sto 
select ali the Any Widget Chain buttons, which will match every widget in the 
application. Asyou select different buttons, the tree display will update to show you 
exactiy which widgets will beaffected by the current resource specification. 
N ormai and Constraint Resources Thenext area ali ows you to select the name of the normal or constraint resources 

you wish to set. Somewidgetsmay not have constraint resources, so that area will 
not appear. 

Thisnext area allowsyou to enter the resource value Thisvalueshould beentered 
exactiy asyou would type a line into your resource fi le Thus, it should contai n no 
unescaped newlines. Thereareafew special character sequences for this file: 
\n- Thiswill bereplaced with a newline. 

\###- Where# isany octal digit. Thiswill bereplaced with a single 

byte that contai nsthissequence interprete^ asan octal 
number. Forexample, avaluecontainingaNULL byte can be 
stored by specifying 
\<new-iine>- Thiswill compressto nothing. 
\\- Thiswill compressto a single backslash. 



ResourceValue 



Parti: U ser Commands 



Command Area Thisareacontainsseveral command buttons, described in thefollowing list: 

TheSet Save File button allows the user to modifyfilethattheresourceswill be 
saved to. This button will bring up a dialog box that wi II ask you for afilename; 
after the fi lenamehasbeen entered, either hit carri age- return or click on the 
Okay button. To pop down thedialog boxwithout changingthesavefile, click 
theCancel button. 

The Save button will append the resource line already described to the end of the 
currentsavefile. If no save file hasbeen set, the Set Save File dialog box will be 
popped upto prompttheuserforafilename. 

TheApply button atterri ptsto perform axtsetvaiues cali on ali widgets that 
match the resource li ne described earlier. T hevalue specified isapplied directly 
to ali matching widgets. This behavior isan atterri ptto giveadynamicfeel to the 
resource editor. Sincethisfeature allows usersto put an application in statesit 
may not bewillingto handle, a hook hasbeen provi ded to allow speci fi c 
applicationsto block these setvaiues requests. (See"Blocking editres Requests," 
following). 

U nfortunately, dueto design constraintsimposed on thewidgetsby theX 
Toolkit and the Resource M anager, tryingto coercean inherently stati c system 
into dy n amie behavior can cause strange results. Thereis no guarantee that the 
resultsofan applywill be the sameaswhat will happen when you save the value 
and restart the application. Thisfunctionality is provi ded to try to giveyou a 
rough feel forwhatyour changeswill accomplish, and the results obtained 
should beconsidered suspect at best. H avingsaid that, this isoneof theneatest 
featuresof editres, and I strongly suggest that you play with it, and seewhat it 
can do. 

The Save and Apply button combines the Save and Apply actions described 
earlier into one button. 

ThePopdown Resource Box button will remove the resource box from the 
display. 

BLOCKING editres REQUESTS 

The editres protocol hasbeen built into theAthena W idget set. This allows ali appi ications that arelinked againstxawto be 
ableto speak to the resource editor. Although this provi desgreat flexibility, and isauseful tool, it can quiteeasily beabused. 
It istherefore possi ble for any xaw application to specify a value for the editresBiock resource to keep editres from divulging 
information about itsinternals, orto disablethesetvaiues part of the protocol. 

editresBiock (C lass Editresbiock) specifies which type of blocking this application wishesto impose on the editres protocol. 
T he accepted values are as follows: 
ali Block ali requests. 

setvaiues Block ali setvaiues requests. Asthis isthe only editres request that actually modifiesthe application, this 
isin effect stati ng that the application isread-only. 

none AllOW ali editres requests. 

Remember that these resources are set on any xaw application, not editres. They allow individuai applicationsto keep ali or 
some of the requests editres makesfrom ever succeeding. Of course, editres isalso an xaw application, so it may also be 
viewed and modified by editres (rather recursive, I know); these commands can beblocked by settingtheeditresBiock 
resource on editres itself. 

RESOURCES 

For editres, the available application resources are as follows: 

nuniFiashes (C lassNumFiashes) specifies the number of ti mes the widgets in the application will beflashed when the Show 
Active Widgets command in invoked. 
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fiashTime (C lassFiashTime) specifies the mount of timebetween the flashes descri bed in the precedi ng entry, 
fiashcoior (C lassf ìashcoior) specifies the color used to flash application widgets. A bright color should beused that will 
immediately draw your attenti on to the area bang flashed, sucri as red or yellow. 

saveResourcesFiie (ClasssaveResourcesFiie) is the file the resource line will beappend to when theSavebutton activated i 
theresource box. 

WIDGETS 

In order to specify resources, it isuseful to know thehierarchy of the widgets that compose editres. In thefollowing 
notation, indentation indicates hierarchical structure. The widget class nameisgiven first, followed by thewidget instance 
name. 

Editres editres 

Paned paned 
Box box 

MenuButton commands 

SimpleMenu menu 

SmeBSB sendTree 

SmeBSB refreshTree 

SmeBSB dumpTreeToFile 

SmeLine line SmeBSB getResourceList 

SmeLine line 

SmeBSB quit 
MenuButton treeCommands 

SimpleMenuumenu 

SmeBSB showClientWidget 

SmeBSB selectAll 

SmeBSB unselectAll 

SmeBSB invertAll 

SmeLine line 

SmeBSB selectChildren 

SmeBSB selectParent 

SmeBSB selectDescendants 

SmeBSB selectAncestors 

SmeLine line 

SmeBSB showWidgetNames 

SmeBSB showClassNames 

SmeBSB showWidgetIDs 

SmeBSB showWidgetWindows 

SmeLine line 

SmeBSB f lashActiveWidgets 
Paned hPane 

Panner panner 

Label userMessage 

Grip grip 
Porthole porthole 

Tree tree 

Toggle <name of widget in application> 



TransientShell resourceBox 

Paned pane 

Label resourceLabel 

Form namesAndClasses 

Toggle dot 

Toggle star 

Toggle any 

Toggle name 
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Toggle class 

Label namesLabel 
List namesList 
Label constraintLabel 
List constraintList 
Form valueForm 
Label valueLabel 
Text valueText 
Box commandBox 
Command setFile 
Command save 
Command apply 
Command saveAndApply 
Command cancel 
Grip grip 

Grip grip 

ENVIRONMENT 

display To get thedefault host and display number 

xenvironment To get the name of a resource fi le that overrides the global resourcesstored in the resource jianager 
property. 

FILES 

<xRoot>/iib/xn/app-defauits/Editres specifies required resources. 

SEEALSO 

x(l), xrdb(l), AthenaWidget Set 

RESTRICTIONS 

Thisisa prototype. Therearelotsof nifty features I would loveto add, but I hopethiswill giveyou someideasaboutwhata 
resource editor can do. 

AUTHOR 

Chris D . Peterson (formerly M IT X Consortium) 
X Version 11 Release6 

elvis, ex, vi, view, input 

elvis, ex, vi, view, input — The editor 

SYNOPSIS 

elvis [f I ags ] [+cmd ] [f i I es . . . ] 

D ESC RIFIO N 

eivis is a text editor that emulates vi/ex. 

On systemswhich pass the program nameasan argument, such asU N IX and M inix, you may also instali elvis under the 
namesex, vi, view, and input. These extra names would normally belinksto elvis; seethem shell command. 



eìuis, ex, vi, niew, input 



When eivis isinvoked asvi, it behaves exactly asthough itwasinvoked aseivis. H owa/er, if you invokeeivis asview, then 
thereadoniy option isset asthough you had given it the -r flag. If you invokeeivis asex, then eivis will start up in the 
colon command modeinstead of the visual command mode, asthough you had given it the - e flag. If you invokeeivis as 
input or edit, then eivis will start up in input mode, asthough the -i flag was given. 



OPTIONS 



-t tag 
-m [file] 



-w winsize 



+command Or -c command 



FILES 

/tmp/elv* 
tags 

.exrc Or elvis . re 



ENVIRONMENT 

TERM 
TERMCAP 



TERMINFO 



LINES, COLUMNS 



EXINIT 



To thereal vi, thisflag meansthata previousedit should berecovered. eivis, though, hasa 
separate program, called eivrec(l), forrecoveringfiles. W hen you invokeeivis with -r, eivis will 

teli yOU tO run elvrec. 

Thissetsthereadoniy option, so you won't accidentally overwriteafile. 
Thissetsthesater option, which disablesmany potenti al ly harmful commands. It hasnot been 
rigorously proven to beabsolutely secure, however. 
Thiscauses eivis to start editing at the given tag. 

eivis will search through file for somethingthat lookslikean errar messagefrom acompiler. It 
will then begin editing the source file that caused the errar, with thecursor sitti ng on thelinewhere 
the errar was detected. If you don't explicitly nameafile, then erriist isassumed. 
eivis will start up in colon command mode 
eivis will start up in visual command mode, 
eivis will start up in input mode 

SetS thewindow Option'SvaluetO winsize. 

If you usethe+command parameter, then after thefirst file isloaded, command isexecuted asan ex 
command. A typical examplewould beeivis +237 too, which would causeeivis to start editing 
too and then move d i recti y to li ne 237. The -c command vari ant was added for UN IX SysV 
compati bility. 



During editing, elvis storestext in atemporary file For U N IX, thisfilewill usuai ly bestored in 
the /tmp directory, and thefirst threecharacters will beeiv. For other systems, thetemporary files 
may bestored som eplace else; seetheversion-specific section of thedocumentation. 
Thisis the database used by the :tags command and the -t option. It isusually created by the 
ctags(l) program. 

On UN IX-like systems, a file called .exrc in your home directory isexecuted asaseriesof ex 
commands. A fileby thesamenamemay beexecuted in thecurrent directory, too. On non-U N IX 
systems, .exrc isusually an invalid filename there, theinitialization file is called elvis. re instead. 



Thisisthenameof your termi nal's entry in thetermeap or terminfo database. The list of legai 
values vari es fra m one system to another. 

Optional. If your system usestermeap, and theTERMCAP variable is unset, then elvis will read your 
termi nal's definition from /etc/termeap. If termcap isset to the full pathnameof a file {starting with 
a /) then elvis will look in thenamed file instead of /etc/ termcap. If termcap isset to a value which 
doesn't start with a /, then its value isassumed to be the full termcap entry for your terminal. 
Optional. If your system uses terminto, and the terminfo variable is unset, then elvis will read your 
termi nal's definition from the database in the/usr/iib/terminto database. If terminfo isset, then its 
value is used as the database nameto use instead of /usr/iib/terminto. 
Optional. These vari ables, if set, will overridethescreen size values given in thetermeap/terminfo 
for your terminal. On windowing systems such asX, elvis has other ways of determi ni ng the 
screen size, so you should probably leave these vari ables unset. 

Optional. This variablecan hold ex commands which will beexecuted instead of the .exrc filein 
your home directory. 
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shell Optional. ThesHELL vari ablesets the default valuefor the sheii option, which determi neswhich 

shell program isused to perform wildcard expansion in filenames, and also which isused to execute 
fi Iters or external programs. The default valueon U N IX systemsis/bin/sh. 
N ote: U nder M S-DOS, thisvariable is called comspec instead of shell. 

home This variable should beset to thenameof your home directory, eivis looksfor its initialization file 

there; if home isunset, then the initialization fi le wi II not beexecuted. 

tagpath Optional. Thisvariable isused by theref program, which isinvoked by theshift-K, control-], 

and :tag commands. Seeref formoreinformation. 

tmp, temp Theseoptional environmentvariablesareonly used in non-UN IX versionsof eivis.Theyallow 

you to supply a di recto ry nameto be used f or stori ng tempo rary files. 

SEE ALSO 

ctags(l), ref(l), elvprsv(l), elvrec(l) 

Elvis— A Clone of Vi/Ex, the complete eivis documentation. 
BUGS 

There is no Lisp support. Certain other featuresaremissing, too. 

Auto-i ndent mode is not quite compati blewith thereal vi. Among other things, o"d and ""d don't do what you might 
expect. 

Long linesaredisplayed differently. Thereal vi wraps long linesonto multiple rowsof thescreen, but elvis scroi Issideways. 
AUTHOR 

Steve Kirken dal I (kirkenda?cs. pdx.edu) 

M any other peoplehaveworked to port elvis to vari ous operati ng systems. To seewho deserves credit, run the :version 
command from within elvis, or look in thesystem-specific section of the complete documentation. 

elvprsv 

eivprsv— Preserve the modifi ed versi on of a fi le after a crash 
SYNOPSIS 

elvprsv ["-why elvis died"] /tmp/f i I e n a me . . . 
elvprsv -R /tmp/f i I e n a me . . . 

D ESC RIFIO N 

elvprsv preservesyour edited text after elvis dies. Thetext can berecovered later, viatheeivprsv program. 

For UN IX-like systems, you should never need to run this program from the command line. It is run automati callywhen 
eivis isabout to die and it should berun (via /etc/rc) when the computer isbooted. TH AT'S ALL! 

For non-UN IX systems such asM S-DOS or VM S, you can either use elvprsv the samewayas under UNIX systems (by 
running it from your autoexec.bat file), or you can run itseparately with the - r flag to recover the files in onestep. 

If you're editing a file when elvis dies (due to a bug, system crash, power fai Iure, and so on), then elvprsv will preserve the 
most recent version of your text. The preserved text isstored in a special directory; it does not overwrite your text file 
automati cai ly. (If the p reservati on directory hasn't been set up correctly, then elvprsv will simply send you a mail message 
describing how to manually run elvprsv.) 

elvprsv will send mail to any user whosework it preserves, if your operati ng system normally supports mail. 



elvrec 




FILES 

/tmp/eiv* Thetemporaryfilethateiviswasusingwhen it di ed. 

/usr/preserve/p* T he text that is preserved byeivprsv. 

/usr/ preserve/ index A text file which lists the names of ali preserved files, and the namesof the /usr/preserve/p* files 
that contai n their preserved text. 

BUGS 

Dueto thepermissionson the/usr/preserve directory, on UN IX systems eivprsv must berun assuperuser. Thisis 
accomplished by makingtheeivprsv executablebeowned by root and turni ng on its "set user id" bit. 

If you're editing a nameless buffer when eivis dies, then eivprsv will pretend that the filewasnamed foo. 
AUTHOR 

Steve Kirken dal I (kirkenda@cs.pdx.edu) 

elvrec 

eivrec— Recover the modified version of a file after a crash 
SYNOPSIS 

elvrec [preservedf i I e [ n e wf i I e ] ] 

D ESC RIFIO N 

If you're editing a file when eivis dies, the system crashes, or power fai Is, themost recent version of your text will be 
preserved. The preserved text isstored in a speci al directory; it doesnot overwrite your text file automatically. 

The elvrec program locates the preserved version of agiven file and writes it over the top of your text file— or to a new file, 
ifyou prefer. Therecovered filewill havenearly ali of your changes. 

To seea list of ali recoverable files, run elvrec with no arguments. 



NOTE 



Ifyou haven't set up a directory for file preservation, you'll haveto manually run theeivprsv program instead of elvrec. 



FILES 

/usr/preserve/p* T he text that was preserved when eivis died. 

/usr/preserve/ index A text fi le that lists the names of ali preserved files, and the namesof the /usr/preserve/p* files that 
contai n their preserved text. 

BUGS 

elvrec isvery picky about filenames. You must teli it to recover thefi le usi ng exactly the samepathnameas when you were 
editing it. Thesimplest way to do this isto go into the same directory that you were editing, and invoke elvrec with the 
samefilenameaseivis. If that doesn't work, then try running elvrec with no arguments, to see exactly which pathnameit is 
usi ng for the desi red file. 

Dueto thepermissionson the /usr/preserve directory, on U N IX systems elvrec must be run assuperuser. Thisis 
accomplished by making the elvrec executable beowned by root and setti ng its "set user id" bit. 

If you're editing a nameless buffer when eivis dies, then elvrec will pretend that the fi le was named foo. 
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AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 



emacs 

emacs— GNU project emacs 

SYNOPSIS 

emacs [ command-line switches ] [files ... ] 

DESCRIPTION 

GNU emacs isa version of emacs, written by the authorof the originai (PDP-10) emacs, Richard Stai Iman. 

Theprimary documentati on of GN U emacs isin theGN U EmacsM anual, which you can read online usi ng info, a 
subsystem of emacs. Please look therefor complete and up-to-date documentation. Thisman pageisupdated only when 
sorrisone volunteersto do so; the emacs maintainers' priority goal isto minimizetheamount of ti me thisman pagetakes 
away from other moreuseful projects. 

The user functi onality of GN U emacs encompasseseverything other emacs editorsdo, and it iseasily extensible sirice its 
editing commands are written in Lisp. 

emacs has an exten si ve i n teracti ve h el p facility, but the faci lity assumesthat you know how to mani pulate emacs Windows and 
buffers. Ctrl+h (backspaceor Ctrl+h) enterstheH elp facility. H elpTutorial (C tri-m t) requestsan i n teracti ve tuto ri al that 
can teach begi nners the fundamentalsof emacs in a few minutes. H elp Apropos (Ctrl+h a) helpsyou find acommand given 
itsfunctionality, H elp Character (Ctrl+h c) describesa given character's effect, and H elp Function (Ctrl+h f) describesa 
given Lisp function specified by name. 

emacs'sUndo can undo several steps of modification to your buffers, so it is easy to recover from editing mistakes. 

GNU emacs'smany special packageshandlemail reading (RMaii) and sending (Mail), outlineediting (outiine), compiling 
(compile), running subshells within emacs windows(sneii), running a Lisp read-eval-print loop (lìsp- interaction -Mode), and 
automated psychotherapy (Dootor). 

There isan extensivereferencemanual, but users of other emacses should have little troubleadapting even without a copy. 
Users new to emacs will beableto use basic featuresfairly rapidly by studying the tutori al and using theself-documentation 
features. 

OPTIONS 

T he followi ng opti ons are of general i nterest: 

file Editfile. 

+n u mb e r Go to the li ne specified by number (do not insert a space between the + sign and thenumber). 

-q Do not load an init file, 

-u user Load user'sinit file. 

-t file Use specified fi le as the terminal instead of using stdin/stdout. Thismust be the first argument specified 

in thecommand line. 

The followi ng options are Lisp-oriented (these opti ons are processed in theorder encountered): 

-f function ExeCUtethe Lisp function functi on. 

-ì file Load the Lisp code in the fi leti i e. 

Thefollowing options are useful when running emacs asabatch editor: 

-batch Edit in batch mode. The editor will send messagesto stdout. Thisoption must be the first in the 

argument list. You must use -1 and -f optionsto specify files to executeand functionsto cali, 
-kiii Exit emacs while in batch mode. 
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-name name 



-font font, -fn f ont 



USING emacswiTHX 

emacs hasbeen tailored to work well with theX Window System. If you run emacs from under X Windows, it will create its 
own X window to display in. You will probably want to start the editor as a background processso thatyou can continue 
usingyour originai window. 

emacs can bestarted with thefollowingX switches: 

-rn nane Specifies the program namewhich should beused when lookingup defaults in the 

user'sX resources. This must be the first option specified in thecommand line. 
Specifies the name that should beassigned to the emacs window. 
D isplay the emacs window in reverse video. 
Usethe"kitchen sink" bitmap icon when iconifying theemacs window. 
Set theemacs wi ndow's font to that specified by font. You will find thevariousX 
fontsin the/usr/iib/xii/fonts directory. N otethat emacs will only acceptfixed 
width fonts. U nder the X 11 Release4font-naming conventi ons, any font with the 
valuem or c in theeleventh field of the font nameisafixed width font. Furthermore, 
fonts whose name are of the form widthxheight are general lyfixed width, asisthe 
fontfixed. Seexisfonts(l) for moreinformation. 

When you specify a font, besureto put a space between theswitch and the font 
name 

Set theemacs window's border width to thenumber of pi xels specified by pixels 
Defaults to one pixel on each sideof thewindow. 

Set the window's internai border width to the number of pixels specified by p i x e i s. 
Defaults to one pixel of paddi ngon each sideof thewindow. 
Set theemacs wi ndow's width, height, and positi on as specified. The geo met ry 
specifi cation is in the standard uformat; seex(l) for moreinformation. The width 
and height are specified in characters; the default is 80 by 24. 
On color displays, sets the color of thetext. Seethefile/usr/iib/xn/rgb.txt fora 
list of valid color names. 

0 n color displays, sets the color of the window's background. 
On color displays, sets the color of the window's border. 
0 n color displays, sets the color of the wi ndow's text cursor. 
0 n color displays, sets the color of the wi ndow's mouse cursor. 
-display di spi ay name C reate the emacs window on the display specified by di spi ayname. M ust bethefirst 
option specified in thecommand line, 
-nw Tells emacs notto use its special interface to x. If you usethisswitch when invoking 

emacs from an xterm(l) window, display isdonein that window. This must bethe 
first option specified in thecommand line. 

You can set x default valuesforyour emacs Windows in your xresources file seexrdb(l). U se the following format: 

emacs. keyword : v a I ne 

wherevai ne specifies the default valueof keyword, emacs letsyou set default values for the following keywords: 



-b pixels 



-ib pixels 



-geometry geomet r y 



-fg color 

-bg color 
-bd color 
-cr color 
-ms color 
-d d i s pi ay n a me , 



font (Class Font) 

reverseVideo (class ReverseVideo) 
bitmaplcon (class Bitmaplcon) 
borderWidth (claSSBorderWidth) 
internalBorder (class BorderWidth) 
foreground (class Foreground) 
background (class Background) 
borderColor (class BorderColor) 



Sets the window's text font. 

If reversevideo'svalueis setto on, thewindow will bedisplayed in reverse video. 

If bitmaplcon's value is set to on, thewindow will iconify into the "kitchen sink." 

Sets the window's border width in pixels. 

Sets the window's internai border width in pixels. 

For color displays, sets the window's text color. 

For color displays, sets the window's background color. 

For color displays, sets the color of the window's border. 
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cursorColor (class Foreground) 
pointerColor (class Foreground) 
geometry (claSSGeometry) 
title (Class Title) 
iconName (class Title) 



For color displays, sets the color of thewindow'stext cursor. 

For color di splays, sets the color of the window's mouse cursor. 

Sets the geometry of theemacs window. 

Sets thetitleof theemacs window. 

Sets the icori name for theemacs window icon. 



If you try to set color valueswhileusinga black-and-white di splay, the wi ndow's characteri sti cs wi 1 1 default asfollows: The 
foreground color wi II beset to black, the background color wi II beset to white, the border color wi II be setto gray, and the 
text and mouse cursorswi II be setto black. 

USING THE MOUSE 

Thefollowing lists the mouse button bindings for theemacs window underXll. 



M OU9S Button 



Function 



left Set poi nt. 

middle Pastetext. 

right C ut text i nto X cut buffer. 

Shift+middle C ut text i nto X cut buffer. 

Shift+right Pastetext. 

Ctrl+middle Cut text into X cut buffer and kill it. 

C trl+ri ght Select this window, then split it into two Windows. SameastypingCtrl+x2. 

Ctrl+Shift-Heft X buffer menu; hold thebuttonsand keysdown, wait for menu to appear, select buffer, and 
rdease. M ove mouse out of menu and releaseto cancel. 

Ctrl+Shift+middle X help menu; pop up index card menu for emacs help. 

Ctrl+Shift-H'ight Select window with mouse, and delete ali other Windows. SameastypingCtrl+xl. 



MANUALS 

You can order printed copiesof theGN U Emacs M anual from the Free Software Foundation, which developsGN U 
software. SeethefileoRDERs for ordering informati on. 

Your locai emacs maintainer mightalso have copies available. Aswith ali software and publicationsfrom FSF, everyoneis 
permitted to makeand distri bute copiesof theemacs manual. TheTeX sourceto themanual isalso included in theemacs 
source distri bution. 



FILES 



/usr/local/info 

/usr/local/lib/emacs/$VERSION/src 
/usr/local/lib/emacs/$VERSION/lisp 

/usr/local/lib/emacs/$VERSION/etc 
/usr/local/lib/emacs/$VERSION/etc/DOC* 



Files for the info documentation browser (a subsystem of emacs) to 
referto. Currently not much of U N IX isdocumented here, but the 
complete text of theemacs reference manual isincluded in a 
convenienttreestructured form. 
C source files and object files. 

Lisp source files and compiled fi lesthat define most editing com- 
mands. Some are preloaded; othersareautoloaded from this directory 
when used. 

Various programsthat are used with GNU emacs, and somefilesof 
information. 

Containsthe documentation stri ngs for the Lisp primitives and 
preloaded Lisp functionsof GNU emacs. They are stored hereto 
reduce the sizeof emacs proper. 
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/usr/local/lib/emacs/$VERSION/etc/DIFF D ÌSCUSSesGN U emacs verSUSTwenex emacs. 

/usr/local/lib/emacs/$VERSION/etc/CCADIFF D ÌSCUSSesGN U emacs V8"SUSCCA emacs. 

/usr/local/lib/emacs/$VERSION/etc/GOSDIFF D ÌSCUSSesGN U emacs verSUS GOSling emacs. 

/usr/iocai/iib/emacs/$vERsioN/etc/SERvicE Lists people offering various servi cesto assist users of G N U emacs, 

including education, troubleshooting, porting, and customization. 
Thesefilesalso haveinformation useful to anyonewantingto write 
programs in the emacs Lisp extension language, which has not yet 
been fui I y documented. 

/usr/iocai/iib/emacs/iock H oldslock filesthat are made for ali files being modified in emacs, to 

preventsimultaneousmodification of onefilebytwo users. 

/usr/iocai/iib/emacs/$vERsioN/$ARCHiTECTURE/cpp TheGN U cpp, needed for building emacs on certain versionsof 

UN IX where the standard cpp cannot handle long namesfor macros. 

/usr/iib/xn/rgb.txt List of vai i d x color names. 

BUGS 

T here ÌS a mai li ng list, bug -gnu-eniacs@prep.ai.mit . edu On the I nternet (ucbvax! prep .ai.mit . edu ! bug -gnu - emacs On 

UUCPnet), for reporti ng emacs bugsand fixes. But before reporting something asa bug, pleasetry to besurethat it really isa 
bug, not a mi sunderstanding or a deliberate feature. Weask you to read thesection "Reporting emacs Bugs" neartheend of 
the reference manual (or info system) for hintson how and when to report bugs. Also, include the version number of the 
emacs you are runni ng i n every bug report that you send i n. 

Do not expect a personal answer to a bug report. The purposeof reporting bugsisto get them fixed for everyonein thenext 
release, if possible. For personal assistance, look in the service fi le for a I ist of peoplewho offer it. 

Pleasedo not send anything but bug reportsto this mailing list. Send requeststo beadded to mailing lists to the special list 
info-gnu-emacs-requestÉ>prep. ai. mit.edu (or thecorresponding U U C P address). For moreinformation about emacs mailing 
lists, seethefile /usr/iocai/emacs/etc/MAii_iNGLisTs. Bugstend actually to be fixed if they can be isolateci, so it isin your 
interest to report them in such away that they can beeasily reproduced. 

One bug that I know about: Shell will not work with programs runni ng in Raw modeon someU N IX versi ons. 
UNRESTRICTIONS 

emacs i s f ree; anyonemay redistribute copies of emacs to anyone under the terni sstated in the emacs General Public License, a 
copy of which accompanieseach copy of emacs and which also appears in the reference manual. 

Copi esof emacs may sometimes be received packaged with di stributi ons of U N IX systems, but it isnever included in the 
scope of any licensecovering those systems. Such inclusion violatesthetermson which distri bution is permitted. In fact, the 
primary purposeof the General Public License i sto prohibit anyone from attaching any other restrictionsto redi stri bution 

Of emacs. 

Richard Stallman encourages you to improve and extend emacs, and urges that you contri bute your extensionsto theGN U 
library. Eventually GN U (GN U 's N ot U N IX) will beacomplete replacement for Berkeley U N IX. Everyone will befreeto 
use, copy, study, and change theGN U system. 

SEE ALSO 

x(l), xlsfonts(l), xterm(l), xrdb(l) 

AUTHORS 

emacs waswritten by Richard Stallman and the F ree Software Foundation. Joachim M arti 1 1 o and Robert Krawitz added theX 
features. 
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emacstool 

emacstooi— Run emacs under Sun Windows with function key and mouse support. 
SYNOPSIS 

emacstool [ {window_args} {-re run_command_path} args ... ] 

TYPICAL USAGE 

In "/.suntoois or "/.rootmenu, include a line li ke this: 

"Emacstool" emacstool -WI emacs. icon -f emacstool-init 

D ESC RIFIO N 

emacstool createsa SunView f rame and atty subwindow within which mouse events and function keysaretranslated to 
ASCII sequencesthat emacs can parse. The translated input events are sent to theprocessrunning in thetty subwindow, 
which istypically GNU emacs. emacstool thereby allowsGN U emacs usersto makefull useof the mouse and function keys. 
GNU emacs can beloaded with functionsto interpret the mouse and function-key events to makea truly finescreen-oriented 
editor for the Sun Workstation. 



NOTE 



GNU emacs has a special interface to theX Window System aswell. TheX Window System hasmany technical advan- 
tages, itisan industry standard, and itisalsofreesoftware.TheFreeSoftwareFoundation urgesyou to tryX Windows, 
and distributes a free copy of x on emacs distri bution tapes. 



Function keysaretranslated to a sequence of the form 'Via-o] [irti. The last character isi, r, ort, correspondingto 
whether the key isamongtheLeft, Right, or Top function keys. The third character indicates which button of thegroup was 
pressed. Thus, the function key in thelower-right corner wi II transmit the sequence -x*or. In addition, the [irti isaffected 
by the Control, M età, and Shift keys. U nshifted Ctrl keys wi II benonalphabetic: C-l is [,], C-r is[2], C-t is [4] . 

M ousebuttonsareencoded as"x"@([i24] x y)\n. ~r® is the standard GN U emacs mouse event prefix; it isfollowed by a list 
indicating the button pressed and the character row and column of the poi nt in the window where the mouse cursor is, and 
followed by a newl ine character. In GN U emacs, the "x"? dispatchesto a mouse event handler which then readsthefollowing 
list. 

OPTIONS 

emacstool supports ali the standard window arguments, includi ng font and icon specifiers. 

By default, emacstool runs the program emacs in thecreated subwindow. Thevalueof theenvironment variableEMAcsTooL 
can beused to overridethisif your version of emacs isnot accessi bleon your search path by the name emacs. In addition, the 
run command can beset by thepathnamefollowing thelast occurrenceof the -re flag. Thisisconvenient for usi ng emacstool 
to run on remote machines. 

Ali other command-l ine arguments notused by the window system arepassed as arguments to the program that runs in the 

emacstool Window. 

Forexample, 

local% (emacstool -re rlogin remote -8 &)& 

will create an emacstool window logged in to a machine named remote. If emacs isrun from thiswindow, emacstool will 
encode mouse and function keys, and send them to riogin. If emacs isrun from thisshell on the remote machine it will see 
the mouse and function keysproperly. H owever, si nce the remote host doesnot have access to thescreen, the cursor cannot 
bechanged, menuswill not appear, and theselection buffer (stuff) islimited. 




USING WITH GNU emacs 

T he G N U emacs filffi lisp/term/sun . el, lisp/sun- mouse. el, lisp/sun-f ns . el, and src/sunf ns.c provide emacs Support 

for theemacstooi and function keys. emacstooi will automatically set the term environment variableto besun and unset 
theenvironment variable termcap. That is, these vari ables will not beinherited from theshell that startsemacstooi. Sincethe 
terminal type ìssun (that is, the environment variable term issetto sun), emacs will automatically load thefileiisp/term/sun. 
This, in turn, will ensurethat sun -mouse. ei isautoloaded when any mouse events are detected. It issuggested that sun -mouse 
and sun-fns beloaded in your site-init.ei file, so that they will alwaysbeloaded when runningon a Sun workstation. 

In addition, emacstooi sets the environment variable in_emacstool = "t". Lisp codein your '/.emacs can use (getenv 
"in_emacstool") to determ i ne whether to do emacstooi-specific initialization. sun.ei usesthisto automatically cali emacstooi- 

init if (getenv " IN_EMACSTOOL" ) isdefined. 

The file src/sunf ns.c defines several useful functionsfor emacs on the Sun. Among these are proceduresto pop up SunView 
menus, put and get from the SunView stufe buffer, and a procedure for changing thecursor icon. If you wantto define or 
edit cursor icons, thereisa rudimentary mouse-driven icon editor in thefileiisp/sun-cursors.ei. Try invoking (sciedit- 

cursor) . 

BUGS 

Ittakesafew millisecondsto createamenu beforeit popsup. 
ENVIRONMENT VARIABLES 

EMACSTOOL, IN_EMACSTOOL, TERM, TERMCAP 

FILES 

emacs 

SEEALSO 

emacs(l), . . . /etc/SUN-SUPPORT, ... /lisp/term/sun .el 

etags 

etags— G enerate tag fi le for emacs 
ctags— G enerate tag fi le for vi 

SYNOPSIS 

etags [ -aCDSVH] [ -i file ][-o tagfile ] 

[ --c++ ] [ - -no-defines] [ --ignore-indentation ] [ --help ] [ --version ] 
[ - -include=f i I e ] [ - -output=t agf I I e ] [ --append ] file ... 

ctags [ -aCdSVH] [ -BtTuvwx ] [ -o tagfile ] 
[ --c++ ] [ --defines ] [ --ignore-indentation ] 

[ - -backward-search] [ - -forward-search ] [ --typedefs ] [ - -typedef s-and-c++] 

[ --no-warn ] [ --cxref ] [ --help ] [ --version ] 

[ - -output=t agf il e ] [ --append ] [ --update ] file ... 

D ESC RIFIO N 

The etags program isused to create a tag table file, in a format understood by emacs(l); the ctags program isused to create a 
si mi lar table i n a format understood by vi(l) . Both formsof the program understand thesyntaxof C, FORTRAN , Pascal, 
LaTeX, Scheme, emacs Lisp/Common Lisp, and most assembler- li kesyntaxes. Both formsread the files specified on the 
command line, and write a tag table (defaults: tags for etags, tags for ctags) in the current working directory. Theprograms 
recognizethelanguageused in an input filebased on its filmarne and contents; thereareno switchesforspecifying the 
language. 
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-append 

-backward-search 



OPTIONS 

Someoptionsmakesenseonly for the vi-style tag file produced by ctags; etags doesnot recognizethem. Theprograms 
accept unambiguous abbrevi ationsfor long option names. 

Append to existing tag file. (Forvi-formattag files, seealso --update.) 
Tag files written in the format expected by vi contai n regular expression search instructions; 
the-B option writesthem usingthedelimiter ?, to search backwardsthrough files. The 
default isto usetheddimiter / to search forwardsthrough files. Only ctags acceptsthis 
option. 

Treat files with .c and .h extensionsas C++ code, note code. Files with .c, .h, .cxx, .hxx, 
or .ce extensionsarealwaysassumed to beC++code. 

C reate tag entri es for C preprocessor defi nitions, too. T his is the default behavior for etags, 
so this option is only accepted by ctags. 

D o not create tag entri es for C preprocessor defi nitions. This may makethetagsfile much 
smaller if many header files are tagged. T his is the default behavior for ctags, so this option 
is only accepted by etags. 

Include a note in tag fileindicatingthat, when searchingforatag, oneshould also consult 
thetagsfilef i e after checki ng the current fi le. Only etags acceptsthis opti on. 
Explicit nameof fi le for tag table; overrides default tags or tags. (But ignored with -v or 



-c, --c++ 



-d, - -def ines 



-D, - -no-defines 



file, - -include=f i I e 



-o tagfile, - -output=t agf 



-S, - -ignore-indentation 



-t, - -typedef s 



-T, - -typedef s-and-c++ 



-update 



-v, - -vgrind 



-w, - -no-warn 



-cxref 



-help 



Don't rely on indentation asmuch aswenormally do. Currently, this means not to assume 
thataclosingbracein thefirstcolumn isthefinal braceof afunction or structure defi nition 
in C and C++. 

Record typedef s in C code as tags. Since this is the default behavior of etags, only ctags 
acceptsthisoption. 

Generate tag entries for typedef s, struct, enum, and union tags, and C++memberfunctions. 

Since this is the default behavior of etags, only ctags accepts thisoption. 

Update tag entries for files specifi ed on command line, leaving tag entries for other files in 

place. Currently, thisisimplemented by deleti ng the existi ng entriesfor the given files and 

then rewritingthenew entries at the end of the tags fi le. It isoften fasterto simply rebuild 

the enti re tag filethan to use this. Only ctags acceptsthisoption. 

Instead of gen erati n g a tag fi I e, write index (in vgrind format) to standard output. Only 

ctags accepts thisoption. 

Suppresswarning messages about duplicate entries. The etags program does not check for 
duplicate entries, so thisoption isnot allowed with it. 

Instead of generati ng a tag file, writeacross-reference(in cxref format) to standard output. 
Only ctags acceptsthisoption. 
Printusage informati on. 

Print the current version of the program (sameas the versi on of theemacs etags isshipped 
with). 



SEEALSO 

emacs entry in info; GNU EmacM anual, Richard Stallman. 

cxref(l), emacs(l), vgrind(l), vi(l). 

COPYING 

Copyright © 1992 F ree Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof this manual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 




Permission isgranted to copy and distri butetranslationsof thismanual into another language, under the above condì ti ons 
for modified versi ons, except thatthis permission noticemay beincluded in translationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

GNU Tools, 19 Aprii 1994 

expand 

expand— Convert tabs to spaces 
SYNOPSIS 

expand [-t a b 1 [ ,t a b 2 [,...]] ] [-t tabi [,tab2 [ , . . .]]] [-i] [ -tabs=t abl [ ,t a b 2 [,...]] ] 
[--ìnitial] [--help] [--version] [file...] 

D ESC RIPTIO N 

Thismanual page documents the GN U version of expand. expand writesthecontentsof each given file, or the standard input 
if none are given orwhen afilenamed - is given, to the standard output, with tab characters converted to the appropriate 
number of spaces. By default, expand convengali tabsto spaces. It preserves backspace characters in the output; they 
decrement thecolumn countfortab calculations. The default action isequivalent to -8 (set tabs every 8 columns). 

OPTIONS 

-, -t, --tabs tabi [,tab2 [, . . .]] 



-i, - -initial 

- -help 
- -version 

GNU TextUtilities 

find 

tind— Search forfiles in a directory hierarchy 
SYNOPSIS 

find [path. . . ] [expressi on ] 

D ESC RIFIO N 

Thismanual page documents the GN U version of find. find searches the directory treerooted at each given filenameby 
evaluating the given expressi on from left to right, accordi ngto therulesof precedence(see"Operators," later in thismanual 
page), until theoutcomeis known (the left side is False for and operations, True for or), at which poi nt find moveson to the 
nextfilename. 

Thefirst argument that begins with -, (, ), ,, or ! istakento bethebeginningof the exp ressi on; any arguments before it are 
pathsto search, and any arguments after it aretherest of the exp ressi on. If no paths are given, thecurrent directory isused. If 
no expression is given, theexpression -print isused. 



If only onetab stop is given, set the tabs tabi spaces apart instead of the default 8. 
Otherwise, set the tabs at columns tabi, t a b 2 , and so forth (numbered from 0) and 
replace any tabs beyond the tab stops given with single spaces. If thetab-stopsare 
specified with the-t or - -tabs option, they can beseparated by blanksaswell asby 
commas. 

Only convert initial tabs (those that precede ali nonspaceortab characters) on each 
lineto spaces. 

Print ausagemessageand exit with a nonzero status. 
Print version informati on on standard output then exit. 



find exitswith status 0 if ali filesareprocessed successfully, greater than 0 if errorsoccur. 
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EXPRESSIONS 

Theexpression ismadeup of options {which affect overall operation rather than the processing of a specific file, and always 
return True), tests (which return a True or False value), and actions (which have side effects and return a True or False value), 
ali separated by operators. -and isassumed wheretheoperator isomitted. If theexpression contai ns no actionsotherthan - 
prune, -print isperformed on ali filesfor which theexpression istrue 

OPTIONS 

Ali options always return True. They always takeeffect, rather than beingprocessed only when their place in theexpression is 
reached. Therefore, for clarity, it isbest to placethem at the beginningof theexpression. 



-daystart 

-depth 
-f ollow 
-help, -help 
-maxdepth I evel s 

-mindepth I evel s 

-mount 

-noleaf 



-version, 
-xdev 



M easuretimes(for-amin, -atime, -cmin, -ctime, -mmin, and -mtime) from thebeginning of today 

rather than from 24 hours ago. 

Processeach directory'scontents before the directory itself. 

Dereferencesymbolic links Im pi ies -noleaf. 

Print asummary of thecommand-lineusageof fìnd and exit. 

Descend at most leve s (a n on negati ve in teger) levelsof directoriesbelow thecommand-line 
arguments. -maxdepth 0 meansonly apply the tests and actions to thecommand-linearguments. 
Do not apply any tests or action sat I evel si ess than 1 evel $ (a nonnegative integer). -mindepth 1 
means process ali fi Ies except the command-line arguments. 

Don't descend directorieson other fi lesystems. An alternate name for -xdev, forcompatibility with 
so m e oth er versi onsoftind. 

Do not opti mizeby assumi ngthat di rectories contai n two fewer su bdi recto ri es than their hard link 
count. Tnisoption isneeded when searchi ng fi lesystems that do notfollow theU N IX directory- 
link convention, such asCD-ROM or M S-DOSfilesystemsor AFS volume mount points. Each 
directory on a normal U N IX fi I esystem hasat least 2 hard links: its name and its . entry. Addition- 
ally, its subdi rectories (if any) each have a . . entry linked to that directory. W hen tind isexamining 
a directory, after it hasstatted two fewer subdi rectories than the di rectory's link count, it knows 
that the rest of the entries in the directory arenondirectories(ieaf fi Ies in the directory tree). If 
only the fi Ies' names need to beexamined, there isno need to stat them; thisgivesa significant 
increasein search speed. 
Pri nt the find version numberand exit. 
D on't descend di rectories on other fi lesystems. 



TESTS 

N umeric arguments can be specified as 
+n Greater than n. 



-anewer file 

-atime n 
-cmin n 
-cnewer file 

-ctime n 

-empty 

-false 



Lessthan n. 
Exactly n. 

Filewas last accessed n minutesago. 

Filewas last accessed more recently than file wasmodified. -anewer isaffected by -foiiow only if - 
f oiiow comes before -anewer on thecommand line. 
Filewas last accessed 11*24 hours ago. 
File's status was last changed n minutesago. 

File's status was last changed more recently than filewas modified. -cnewer isaffected by -foiiow 

only if -foiiow comes before -cnewer on thecommand line. 

File's statuswas last changed n*24 hours ago. 

File is empty and is either a regular fi le or a di rectory. 

Always fai se. 




Fileison afilesystem of typetype. The vali d fi lesystem types vary amongdifferent versionsof 

U N IX; an incomplete list of filesystem types that areaccepted on someversion of U N IX or another 

is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can use-printf with the%F directiveto seethetypes 

of your filesystem s. 

File'snumeric group ID is n . 

Filebelongsto group gname (numeri c group ID allowed). 

Like-iname, but the match is case- in sensi ti ve. 

Like-name, but the match is case-insensitive. Forexample, thepatternsfo* and f?? match the 

filenamesFoo, foo, foo, foo, and so on. 

File hasinode numbern. 

Like-path, but the match is case-insensitive. 

Like-regex, but the match is case- in sensi ti ve. 

Filehasn links. 

File is a symbol ic link whosecontents match shell pattern pattern. The meta characters do nottreat 
/ or . specially. 

File's data was last modified n minutesago. 
File's data was last modified n*24 hoursago. 

Base of filmarne (the path with theleading directories removed) matches shell pattern pattern. The 

meta characters (*, ?, and u) do not match a . at the start of the base name.To ignore a directory 

and thefilesunder it, use-prune; seean examplein the description of -patti. 

Fi le was modified morerecently than file, -newer isaffected by -foiiowonly if -f oiiow comes before 

-neweron thecommand line. 

N o user correspondsto file's numeric user ID . 

N o group correspondsto file'snumeric group ID . 

Filmarne matches shell pattern pattern. The meta characters do nottreat / or . specially; so, for 
example, 

find . - path './sr*sc' 

will printan entry for a directory called ./src/misc (if oneexists). To ignoreawholedirectorytree 
use-prune rather than checking every file in thetree. Forexample, to skip the directory src/emacs 
and ali filesand directories under it, and print thenamesof theotherfilesfound, do something like 
this: 

find . -path './src/emacs' -prune-o -print 

File's permission bitsareexactly mode(octal or symbolic). Symbolic modes use mode 0 asapoint 
of departure. 

Ali of the permission bits mode are set for the fi le. 
Any of the permission bits mode are set for the file 

Filmarne matches regular expression pattern. Thisisamatch on the whole path, notasearch. For 
example, to match afilenamed ./fubar3, you can use the regular expression .*bar. or .*b.*3, but 

notb.*r3. 

Fileusesn unitsof space. The uni ts are 512-byte blocks by default or if b followsn, bytes if c 
followsn, kilobytes if k followsn, or 2-bytewordsif w followsn. Thesizedoesnot count indirect 
blocks, but it does count blocks in sparse fi les that are not actually allocated. 
Alwaystrue 

Fileisof typec. Possi ble types: 
b Block (buffered) special 
c C haracter (unbuffered) special 
d D i rectory 
p Named pipe(FIFO) 
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-uid n 
-used n 
-user u n a me 
-xtype c 

ACTIONS 

-exec command ; 



-fls file 
-f print file 

-f printB file 

-f printf file f or ma t 

-ok command ; 

-print 
-printO 

-printf f or mat 



f Regularfilel symbolic link 
s Socket 

File's numeric user ID isn. 

File was last accessed n days after its status waslastchanged. 
File is owned by user uname (numeric user ID allowed). 

Thesameas-type unlessthefileis a symbolic link. For symbolic links: if -foiiow hasnot been 
given, True if the fi le is a link to afileof type c ; if -foiiow hasbeen given, True if c is 1. In other 
words, for symbolic links, -xtype checks the type of the file that -type doesnot check. 



E xecute command: True if 0 status is return ed. AH following argumentsto find aretaken to be 
argumentsto thecommand until an argumentconsistingof ; isencountered. Thestring o is 
replaced by thecurrent filenamebeing processed everywhereitoccurs in the argumentsto the 
command, not just in argumentswhereit is alone, as in some versionsof find. Both of these 
constructionsmight need to beescaped (with a \) nor quoted to protect them from expansion by 
the shell. Thecommand isexecuted in the starti ng directory. 

True; like -ls but writetO file li ke-f print. 

True; print the full filmarne into filef i i e. If f i i e doesnot existwhen find isrun, it iscreated; if it 
doesexist, it istruncated. Thefilenames /dev/stdout and /dev/stderr arehandled specially; they 
refer to the standard output and standard errar output, respectively. 

True; like -print0 but writetO file like -f print. 
True; like -printf but writetO file like -fprint. 

Like -exec but ask the user first (on the standard input); if theresponsedoes not start with y ory, 
do not run thecommand, and return False. 

True; print the full filenameon thestandard output, followed by anewline. 

True; print the full filenameon thestandard output, followed by a nuli character. Thisallows 

fi lenames that contai n newlinesto becorrectly interpreted by programs that process the find 

output. 

True; print format on thestandard output, interpreti ng n escapesand % di recti ves. Field widthsand 
precisionscan bespecified aswith theprintf C function. U nlike-print, -printf doesnotadd a 
newlineat the end of thestring. The escapes and di recti ves areasfollows: 

\a Alarm beli 

\b Backspace 

\c Stop printingfrom this format immedi ately and flush the output 

\f Form feed 

\n Newline 

\r C arri age return 

\t H orizontal tab 

w V erti cai tab 

\\ A I iterai backslash (V) 

A \ character followed by any other character is treated as an ordì nary character, so they both are 
printed: 

%% A I iterai percentsign. 

%a File's last access time in the format retur ned bytheC ctime function. 

%Ak File's last access time in the format specified byk.which iseither e or a directi ve for theC 
strftime function. T he possi ble values for k are listed below; some of them might not be 
availableon ali systems, dueto differences in strftime between systems. 
©secondssincejan. 1, 1970, 00:00 GM T. 




Timefields 



H HOUr(00..23) 

i H our(0i . .12) 

k Hour(0..23) 

1 H our (1 . .12) 

m M inute (00. .59) 

p Locale'sa.m. or p.m. 

r Time; 12-hOur (hh:mm:ss [AP]M) 

u Second (00. .61) 

T Time 24-hOUr(hh:mm:ss) 

x Locale'stimerepresentation (h:m:s) 

z Timezone(for example, EDT), or nothing if no timezoneis 
determinatile 

Datefields: 

a Locale'sabbreviated weekday name(sun. .sat) 

a Locale's full weekday name, variable length (sunday. .saturday) 

b Locale'sabbreviated month name(jan. .Dee) 

b Locale's full month name, variable length (january.. December) 

c Locale's date and ti me (sat nov 04 12:02:33 est igsg) 

d Day of month (01 . .31) 

D Date(mm/dd/yy) 

b Sameasb 

j Dayofyear(00i..366) 

m M onth (01 . .12) 

u Week number of year with Sunday as first day of week (00. .53) 

w Dayofweek (0..e) 

w Week number of year with M onday as first day of week (00. .53) 

x Locale's date representation (mm/dd/yy) 

y Lasttwo digitsof year (00. .99) 

y Year (1970...) 



%b File'ssizein 512-byteblocks(rounded up). 

%c File'slast status changetime in the format returned bytheC ctime function. 

%ck File'slast status changetime in the format specified by k, which isthesameasfor%A. 

%d File'sdepth in the directory tree; 0 meansthefileisa command-lineargument. 

%f File'snamewith any leading directories removed (only thelast element). 

%f Typeof thefilesystem thefileison; thisvaluecan beused for -fstype. 

%g File'sgroup name ornumeriegroup ID if thegroup hasno name. 

%g File'snumeric group ID . 

%h Leading directories of file's name (ali but thelast element). 

%h Command-lineargumentunderwhich filewasfound. 

%i File's inode number (in decimai). 

%k File'ssizein 1K blocks(rounded up). 

%i 0 bject of symbol ic link (empty stri ng if file is not a symbolic link). 
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%m File's pernii ssion bits (in octal). 
%n N umber of hard links to fi le. 
%p File's name. 

%p File's name with the name of thecommand-lineargument under whi eh itwasfound 

removed. 
%s File's si ze in bytes. 

%t File's last modification timein theformat returned by theC ctime function. 
%Tk File's last modification timein theformat specified by k, which isthesameasfor%A. 
%u File's username, or numeric user ID if the user has no name. 
%u File's numeric user ID . 

A % character followed by any other character is discarded (but the other character is 

printed). 

-prune If -deptn isnot given, True; do not descend thecurrent directory. 

If -deptn isgiven, False; no effect. 
-is True; list current file in is -diis format on standard output. The block counts are of 1K blocks, 

unlesstheenvironmentvariableposixLY_coRRECT isset, in which case512- byte blocks are used. 

OPERATO RS 

Listed in order of decreasing precedence 
( e x p r ) Force precedence. 

! e x p r True if expr is false, 

-not expr Sameas ! expr . 

e x p r i e x p r 2 And (i mplied); expr 2 is not evaluated if ex pr i isfalse. 

exprl -a expr 2 SameaSexprl expr 2. 

exprl -and e x p r 2 Sameas exprl e x p r 2 . 

expri -o e x p r 2 Or; e x p r 2 is not evaluated if ex pr i istrue. 

exprl -or e x p r 2 SameaSexprl -o e x p r 2 . 

exprl, e x p r 2 List; both ex pr i and ex pr 2 are al ways evaluated. The vai ue of expr 1 is discarded; thevalueof the list 

isthevalueof expr 2 . 

SEEALSO 

ìocate(lL), iocatedb(5L), updatedb(lL), xargs(lL) Finding Files (online in info, or printed) 
GNU FileUtilities 



fitstopnm 

fitstopnm— Convert a FITS file into a portableanymap 
SYNOPSIS 

fitstopnm [-image N] [ -noraw] [ -scanmax] [ -printmax] [ -min f][-max f][FITSfile] 

D ESC RIFIO N 

Reads a FITS file as input. Produces a portable pixmap if the FITS file consists of 3 image planes (naxis = 3andNAxis3 = 3), 
a portable graymap if the FITS file consistsof 2 image planes (naxis = 2), or whenever the -image flag is specified. The 
resultsmay need to beflipped top for bottom; if so, just pipe the output through pnmfiip -tb. 




OPTIONS 

The -image option isfor FITSfileswith threeaxes. Theassumption isthatthethird axisisfor multiple images, and this 
option letsyou selectwhich oneyou want. 

Flags -min and -max can beused to overridethemin and max valuesas read from the FITS header or the image data if no 
datamin and datamax keywords are found. Flag -scanmax can beused to force the program to scan the data even when datamin 
and datamax are found in theheader. If -printmax isspecified, theprogram will just printthemin and max valuesand quit. 
Flag -noraw can beused to force the program to produce an ASCII portableanymap. 

Theprogram will teli what kind of anymap iswriting. Ali flags can beabbreviated to their shortest uniqueprefix. 
REFERENCES 

FITS standsfor FlexiblelmageTransport System. A full descri ption can be found in Astronomy& AstrophysicsSupplement 
Series44 (1981), page 363. 

SEEALSO 

pnmtofits(l), pgm(5), pnmflip(l) 

AUTHOR 

Copyright © 1989 byjef Poskanzer, with modificati onsby Daniel Briggs (dbriggs9nrao.edu) and Alberto Accomazzi 

(alberto9cfa.harvard.edu) 

20 September 1989 

fmt 

fmt— Adjust line-length for paragraphsof text 
SYNOPSIS 

fmt [-wi dth ] [f i I es ] . . . 

D ESC RIFIO N 

fmt isasimpletext formatter. It insertsor deletesnewlines, asnecessary, to makeall linesin a paragraph beapproximately the 
samewidth. It preserves indentation and word spacing. 

T he default linewidth is 72 characters. You can override this with the-width flag. If you don't nameany fileson the 
command line, then fmt will read from stdin. 

It istypically used from within vi to adjust the line breaks in a single paragraph. To do this, move the cursorto the top of 
the paragraph, type igfmt, and press Return. 

AUTHOR 

Steve K i rkendal I (kirkenda§cs . pdx . edu ) 

fold 

foid— Wrap each input lineto fit in specified width 
SYNOPSIS 

fold [-bs] [-w width] [-bytes] [-spaces] [ — width=wi dt h ] [-help] 
[ -version] [file...] 




Parti: U ser Commands 



D ESC RIFIO N 

Thismanual page documents the GN U version of foia, foid prints the specifiad files, or the standard input when nofilesare 
given orthefilename- isencountered, on the standard output. It breaks long linesinto multi pie shorter linesby insertinga 
newlineat column 80. It countsscreen columns, so tab characters usually takemorethan onecolumn, backspacecharacters 
decreasethecolumn count, and carri age return characters set the column count back to zero. 

OPTIONS 

-b, -bytes 
-s, -spaces 

-w, — width wi dt h 

— help 

— version 

GNU Text U tilities 

free 

free— D isplay amount of free and used memory in the system 
SYNOPSIS 

free [-b | -k j -m] [ -o] [ -s del ay ] [ -t] 

D ESC RIPTIO N 

free di splays the total amount of free and used physical and swap memory in the system, aswell astheshared memory and 
buffersused by the kernel. 

OPTIONS 

The -b switch displays the amount of memory in bytes; the -k switch (set by default) displays it in kilobytes; the -m switch 
displaysit in megabytes. 

The -t switch displays a line containingthetotals. 

The -o switch disables the display of a "buffer adjusted" line. U nlessspecified free subtracts/adds buffer memory from/to the 
used/free memory reports (respectively!). 

The -s switch activates continuous polling delay secondsapart. You may actually speci fyany floating point number for 
delay, usieep(3) isused for microsecond resolution delay times. 

FILES 

/proc/meminfo M emory i nformation 

SEEALSO 

ps(l), top(l) 

AUTHORS 

Brian Edmonds 

Cohesive Systems, 20 M arch 1993 



Count bytes rather than columns, so thattabs, backspaces, and carriagereturnsareeach counted as 
taking up onecolumn, just like other characters. 

Break at word boundaries. If the li ne contai nsany blanks, the li ne is broken after the last blank that 
falls within themaximum linelength. If there are no blanks, the li ne is broken at the maximum 
li ne length, as usuai. 

Use a maximum linelength of width columns instead of 80. 
Print ausagemessageand exit with a nonzero status. 
P ri nt version i nformation on standard output then exit. 



fslsfonts 



fsinfo 

fsinfo—x font server information utility 
SYNOPSIS 

fsinfo [-server servername] 

D ESC RIFIO N 

fsinfo is a utility for displaying information about an X font server. It isused to examinethecapabilitiesof a server, the 
predefined valuesfor variousparametersused in communicating between clients and the server, and the font catalogues and 
alternate servers that are available. 

EXAMPLE 

The followi ng isasampleproduced by fsinfo. 

name of server: hansen:7100 
version number: 1 

vendor string: Font Server Prototype 
vendor release number: 17 

maximum request size: 16384 longwords (65536 bytes) 

number of catalogues: 1 

ali 

Number of alternate servers: 2 

#0 hansen:7101 

#1 hansen:7102 

number of extensions: 0 

ENVIRONMENT 

fontserver T o get the defaul t fontserver 

SEEALSO 

xfs(l), fslsfonts(l) 

AUTHOR 

D ave Lemke (N etwork C omputing D evices, I ne.) 
X Version 11 Release6 

fslsfonts 

fslsfonts— List fonts served by X font server 
SYNOPSIS 

fslsfonts [-options ...] [-fn pattern] 

DESCRIPTION 

fslsfonts lists the fonts that match thegiven pattern. The wildeard character * may beused to match any sequenceof 
characters (including none), and ? to match any single character. If no pattern isgiven, * isassumed. 

The* and ? characters must bequoted to prevent them from beingexpanded by theshell. 
OPTIONS 

-server h o s t : p o r t T his option specifies the X font server to contact. 

-ì L ists some attributesof the font on onelinein addition to its name. 
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-11 Listsfont propertiesin addition to -1 output. 

-111 Supported for com pati bi lity with xisfonts, but output isthesameasfor-n. 

-m Thisoption indicatesthat long listi ngs should also print the minimum and maximum boundsof 

each font. 

-c Thisoption indicatesthat listi ngs should use multi pie columns. Thisis the sameas-n 0. 

-1 Thisoption indicatesthat listi ngs should use a single column. Thisisthesameas-n 1. 

-w wi dth Thisoption specifies the width in charactersthat should beused in figuri ngout how many 

columns to print. The default is 79. 
-n coi umns Thisoption specifies the number of columns to use in displaying the output. The default is 0, 

which will atterri pt to fit as many columns of font names into the number of character speci fi ed by 

-w width. 

-u Thisoption i ndicates that the output should beleftunsorted. 

SEE ALSO 

xf s(l), showfont(l), xlsfonts(l) 

ENVIRONMENT 

fontserver To get the default host and port to use 

BUGS 

Doingtsisfonts -1 can tieup your server for a very long ti me. Thisis really a bug with single-threaded nonpreemptable 
servers, notwith this program. 

AUTHOR 

D ave Lemke (Network Computing Devices, Inc.) 
X Version 11 Rdease6 1 

fstobdf 

fstobdf— Generate BD F font from X font server 
SYNOPSIS 

fstobdf [ -server server ] -fn fontname 

D ESC RIFIO N 

The fstobdf program reads a font from a font server and printsa BD F fileon the standard output that may beused to 
recreate the font. This is useful in testi ng servers, debugging font metrics, and reproduci ng lost BDF files. 

OPTIONS 

-server s e r v e r n a me Thisoption speci fi es the server from which the font should beread. 
-fn fontname Thisoption specifies the font for which aBDF fileshould begenerated. 

ENVIRONMENT 

fontserver D efault server to use 

SEE ALSO 

xfs(l), bdftopcf(l), fslsfonts(l) 



ftp 




AUTHOR 

Olaf Brandt (N etwork Computing Devices), DaveLemke(N etwork Computing Devices), Jim Fulton (M IT X Consortium) 
X Version 11 Release6 

fstopgm 

fstopgm— Convert aUsenix FaceSaverfileinto a portaPlegraymap 
SYNOPSIS 

fstopgm [f sf il e ] 

DESCRIPTION 

Reads a U senix FaceSaver fi le as input. Produces a portaPle graymap as output. 

FaceSaverfilessometimeshaverectangular pixel s. Although fstopgm won't rescale them into squarepixelsforyou, it will give 
you the precise pnmscalecommand that will do thejoP. Becauseof this, reading a FaceSaver imageis a two-step process. 
First you do 

fstopgm > /dev/null 

Thiswill teli you whetheryou need to usepnmscaie. Then useoneof thefollowing pi pel i nes: 

fstopgm ! pgmnorm 

fstopgm | pnmscale -whatever j pgmnorm 

To go to PBM , you wantsomethingmorelikeoneof these: 

fstopgm | pnmenlarge 3 | pgmnorm j pgmtopbm 

fstopgm | pnmenlarge 3 j pnmscale <whatever> ] pgmnorm | pgmtopbm 

You wantto enlargewhen goingto a Pitmap Pecauseotherwiseyou loseinformation; Put enlarging Py morethan 3 does not 
look good. 

FaceSaver is a regi stered trademark of M etron C omputerware Ltd. of 0 akland, C A. 
SEEALSO 

pgmtofs(l), pgm(5), pgmnorm(l), pnmenlarge(l), pnmscale(l), pgmtopbm(l) 

AUTHOR 

C opyright © 1989 Py J ef Poskanzer 
6 Aprii 1989 

ftp 

ftp— ARPAnetfiletransfer program 
SYNOPSIS 

ftp [-vi [-d] [-i] [-n] [-g] [ho s t ] 

DESCRIPTION 

ftp is the user interface to the ARPA net standard Fi le Transfer Protocol. The program allowsa user to transfer fi lesto and 
from a remote network site. 

Optionsmay Pe specified at thecommand line, orto thecommand interpreter. 



Parti: U ser Commands 



-v Verbose optionforcesttpto show ali responsesfrom the remote server, aswell as 

report on data transfer statistica 

-n Restrainsftp from attempting auto-login upon initial connection. If auto-login is 

enabled, ftp will check the (seebelow) file in the user's home directory foran entry 
describing an account on the remote machine. If no entry exists, ftp will prompt for 
the remote machi ne login name(default istheuser identity on thelocal machine), 
and, if necessary, prompt for a password and an accountwith which to login. 

-i Turnsoff interactiveprompting during multiplefiletransfers. 

-d E nables debugging. 

-g D isables filename giobbi ng. 

The client host with which ftp isto communicatemay bespecified on thecommand line If thisisdone, ftp will immedi- 
ately atterri pt to establish a connection to an FTP server on that host; otherwise, ftp will enter itscommand interpreter and 
await instructionsfrom the user. W hen ftp is awai ti ng commands from the user, the prompt 
ftp> 

isprovided to the user. The following commands are recognized by ftp : 



[co mma n d ] [args] 



ma c r o - n a me [args] 



account [passwd] 



append I ocal ■ f i I e [remote-fi I e] 



beli 

binary 

bye 



ed re mot e- di r ect or y 
cdup 

chmod mode f il e - ria me 
dose 



delete r e mot e- f i I e 



Invokean interactiveshell on the locai machine. If therearearguments, the first is 
taken to beacommand to execute di recti y, with therest of theargumentsasits 
arguments. 

Execute the macro ma c r o ■ n a me that was defi ned with the macdef command. 
Arguments are passed to the macro unglobbed. 

Supply a supplemental password required by a remote system for access to resources 
once a login hasbeen successfully completed. If no argument isincluded, the user 
will be prompted for an account password in a nonechoing input mode. 
Append a locai fileto afileon the remote machi ne. If remote - fi i e isleft unspecified, 
thelocal filename isused in naming the remote fileafter bei ngaltered by anyntrans 
or nmap setti ng. File transfer usesthecurrent setti ngs for type, format, mode, and 

structure. 

Set the fi le transfer type to network ASC 1 1 . T his i s the default type. 
Arrangethat a beli besounded after each file transfer command is completed. 
Set the fi le transfer type to support bi nary i mage transfer. 
Termi nate the FTP sessi on with the remote server and exit ftp. An end of fi le will 
also terminate the session and exit. 

Toggle remote computer filename case mapping during mget commands. W hen case 

ison (default is off ), remote computer filenames with ali lettere in upper case are 

written in the locai directory with the letters mapped to lowercase. 

C hange the working directory on the remote machi ne to remote - di r ect ory . 

C hange the remote machi ne worki ng di recto ry to the parent of the current remote 

machi ne working directory. 

C hange the permission modesof the file f i i e - n a me on the remote system to mode. 
Termi nate the FTP session with the remote server, and return to thecommand 
interpreter. Any defined macros areerased. 

Toggle carri age return stri pping during ASC II type file retri eval. Recordsare 
denoted by acarriagereturn/iinefeed sequence during ASCII type fi le transfer. 
When cr ison (the default), carri age returns are stri pped from this sequence to 
conform with theU N IX single linefeed record delimiter. Recordson non-UN IX 
remote systems may contai n single li nefeeds; when an ASCII type transfer ismade, 
theselinefeedsmay be distingui shed from a record delimiter only when cr isoff. 
D elete the file re mot e- f i i e on the remote machine. 



ftp 



debug [debug- vai u e ] 



dir [remote-directory] [I o c a I ■ f i I e ] 



disconnect 
forni f or ma t 

get r e mo t e - f i I e [I ocat - f i I e ] 



glob 



hash 

help [corrimano 1 ] 
idle [seconds ] 
lcd [directory] 

ls [remote-di rectory] [I ocal ■ f il e ] 



macdef macro- name 



FI 



mdelete [remote-fi I es ] 



Toggle debugging mode. If an optional debug- vai ne isspecified, it isused to set the 
debugging leve!. W hen debugging ison, ftp printseach command sentto the 
remote machine, preceded by the stri ng ->. 

Print a listingof the di rectory contentsin the di rectory, remote - di rect or y, and, 
optional ly, piaci ng the output in i oc ai - f i i e. If interactiveprompting ison, ftp will 
prompt the user to verify thatthelast argument isindeed the target locai filefor 
receivingdir output. If no directory isspecified, the current working directory on 
the remote machine isused. If no locai file isspecified, ori oc ai -f i i e is -, output 
comes to theterminal. 
A synonym forciose. 

Set the fi le transfer form to format .Thedefault format is file. 
Retri ève theremote-fi i e and storeiton thelocal machine. If thelocal filenameis 
not specified, it isgiven the same name it hason the remote machine, subjectto 
alteration by thecurrent case, ntrans, and nmap setti ngs. The current settingsfor 
type, forni, mode, and structure areused whi le transferri ng thefile. 
Toggle fi lenameexpansion for mdelete, mget, and mput. If giobbi ng isturned off with 
giob, thefilenameargumentsaretaken literally and not expanded. Globbing for mput 
isdoneasin csr, 1. Formdeiete and mget, each remote filenameis expanded 
separately on the remote machine and the lists are not merged. Expansion of a 
directory name islikelyto bedifferentfrom expansion of thenameof an ordinary 
file: theexact result dependson the forei gn operati ng system and FTP server, and 
can be previ ewed by doingmis rem ote-fi les Note: mget and mput arenotmeantto 
transfer enti re di rectory subtrees of fi les. T hat can be done by transferri ng a tar 1 
archiveof the subtree (in binary mode). 

Toggle hash-sign (#) printing for each data block transferred. Thesizeof a data block 
is 1024 bytes. 

Print an informativemessageaboutthemeaningof command. If no argument isgiven, 
ftp printsa list of theknown commands. 

Set the inactivity timer on the remote server to seconds seconds. If seconds is 
omitted, thecurrent inactivity timer isprinted. 

C hange the working directory on thelocal machine. If no directory isspecified, the 
user's home di rectory isused. 

Print a listi ng of the contents of a directory on the remote machine. T he listi ng 
includesany system -dependent information that the server choosesto include for 
example, mostsystemswill produce output from thecommand is 1. (Seealso 
niist.) Ifremote-di rectory is left unspecified, thecurrent working directory isused. 
If interactiveprompting ison, ftp will prompt the user to verify thatthelast 
argument isindeed thetarget locai filefor receivingis output. If no locai fileis 
specified, or if i ocal - f i i e is-, the output is sentto theterminal. 
Define a macro. Subsequent linesarestored as the macro ma ero - name; a nuli line 
(consecutivenewlinecharactersin a fi le or carri age returnsfrom theterminal) 
terminates macro input mode. There isa limit of 16 macrosand 4096 total 
characters in ali defined macros. M acros remain defined until a ciose command is 
executed. The macro processor interprets s and \ as special characters. A $ followed 
by a number (or numbers) is replaced by the correspondi ng argument on the macro 
invocation command line. A $ followed by an i signalsthat macro processor that the 
executing macro isto belooped. 0 n the first pass$i is replaced by the first argument 
on the macro invocation command line, onthesecond pass it is replaced by the 
second argument, and so on. A \ followed by any character is replaced by that 
character. U se the \ to prevent special treatment of the$. 
D elete the re mot e- f i i es on the remote machine. 



] 
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mdir r e mot e- f i I es locai ■ f i I e 



mget r e mo t e - f i I e s 



mkdir di rectory-name 

rais r e mot e- f il es oc al • f i I e 



mode [mode - name ] 
modtime f i I e- name 
raput oc al ■ f il es 

newer f il e - name 



nlist [ r e mo t e - di r ect or y ] 
[I ocal -file] 



nmap [inpattern] outpattern 



ntrans [i ne ha r s ] [o ut c har s ] 



Like dir, except multiple remotefilesmay be specified. If interactive prompting is 
on, ftp will prompt the user to verify that thelast argument is indeed the target locai 
filefor receivingmdir output. 

Expand theremot e- f 1 1 es on the remote machine and do aget for each filenamethus 
produced. Seegiob for detailson thefilenameexpansion. Resulti ng fi lenames will 
then beprocessed accordingto case, ntrans, and nmap setti ngs. Filesaretransferred 
into the locai working directory, which can bechanged with ìcd directory ; new locai 
directoriescan becreated with imkdir directory. 
M ake a directory on the remote machine. 

Like niist, except multiple remotefilesmay be specified, and the locai -file must 

be specified. If interactive prompting ison, ftp will prompt the user to verify that 

thelast argument isindeed thetarget locai filefor receivingmis output. 

Set the fi le transfer modeto mode- name. Thedefault mode is stream mode. 

Show thelast modification timeof thefileon the remote machine. 

Expand wildcards in the list of locai files given asarguments and do aput for each 

fi le in the resulti ng list. Seegiob for detailsof filenameexpansion. Resulti ng 

filenameswill then beprocessed accordingto ntrans and nmap settings. 

G et the file only if the modification ti me of the remote fi le is more recent that the 

fileon the current system. If thefile does not exist on the current system, theremote 

fileisconsidered newer. Otherwise, thiscommand isidentical toget. 

Print a list of thefiles in a directory on the remote machine. If remote- di r ect or y is 

left unspecified, the current working directory isused. If interactive prompting ison, 

ftp will prompt the user to verify that thelast argument isindeed thetarget locai file 

for recavi ng mist output. If no locai fi le is specified, or if i ocal - f i i e is-, the 

output is sent to theterminal. 

Set or unset thefilename mapping mechanism. If no arguments are specified, the 
filenamemapping mechanism isunset. If arguments are specified, remote fi lenames 
aremapped duringmput commands and put commands issued without a specified 
remote target fi lename. If arguments are specified, locai fi lenames aremapped during 
mget commands and get commands issued without a specified locai target fi lename. 
Thiscommand isuseful when connecting to a non-U N IX remote computer with 
different file naming conventions or practices. The mapping followsthe pattern set 
by inpattern and outpattern. inpattern isatemplatefor incomingfilenames (which 
may have al ready been processed accordingto thentrans and case settings). Variable 
templating isaccomplished by includi ng the sequences$i , $2, . . ., $9 in inpattern. 
UseUo preventthis special treatment of the $ character. Ali othercharactersare 
treated I iterai ly, and areused to determi ne the nmap inpattern vari ablevalues. For 
example, given inpattern $142 and the remote fi lename mydata. data, $1 would have 
thevaluemydata, and $2 would have the value "data". The outpattern determinesthe 
resulti ngmapped fi lename. The sequences$i, $2,...., $9 arereplaced byanyvalue 
resultingfrom theinpattern template. Thesequence$0 isreplaced by theoriginal 
filename. Additionally, thesequenceseqi, s e q 2 isreplaced byseqi ifseqi isnota 
nuli string; otherwise, it isreplaced by seq2. For example, thecommand nmap 
$1 .$2. $3 [$1 ,$2] . [$2,fiie] would yield the output filenamemyme. data for 

input filenameSmy-file. data and myfile. data. old, myfile.file for the input 

fi lename my -file, and myfile. myfile for the input fi lename .myfile. Spacesmay be 
included in outpattern, asin theexample: nmap $1 sed "s/ *$//" > $i.Usethe\ 
character to prevent special treatment of the$, [, [, and , characters 
Set or unset th e f i I en am e eh aracter tran si ati 0 n mechanism. If no arguments are 
specified, thefilenamecharactertranslation mechanism isunset. If arguments are 
specified, characters in remote fi lenames are translated duringmput commands and 




put commandsissued without a specified remote target fi lename. If argumentsare 
specified, characters in locai filenamesaretranslated duri ng mget commandsand get 
commandsissued without a specified locai target filmarne. Thiscommand isuseful 
when connectingto a non-U N IX remote computer with different fi le nami ng 
conventi ons or practices. Characters in afilenamematchinga character in i nchars 
arereplaced with thecorresponding character in outchars . If thecharacter's positi on 
in i nchars is longer than the length of outchars, the character isdeleted from the 
fi lename. 

Establish a connection to the specified host FTP server. An optional port number 
may be supplì ed, inwhich case, ftp will atterri ptto contact an FTP server atthat 
port. If theauto-iogin option ison (default), ftp will also atterri ptto automatically 
log the user in to the FTP server (see bel ow). 

Toggle interactive prompting. I nteractive prompting occursduring multi pie fi le 
transfersto allow the user to selectively retrieveor storefiles. If prompting isturned 
off (default ison), any mget or mput will transfer ali files, and any mdeiete will delete 
allfiles. 

Executean ftp command on asecondary control connection. Thiscommand allows 
si multaneous connection to two remote FTP serversfor transferri ng fi lesbetween 
thetwo servers. The first proxy command should bean open, to establish the 
secondary control connection. E nter the command "proxy ?" to seeotherttp 
commandsexecutableon the secondary connection. The following commands 
behavedifferently when prefaced by proxy :, open will not define new macrosduring 
theauto-iogin process, dose will not erase existing macro defi nitions, get and mget 
transfer files from the host on theprimary control connection to the host on the 
secondary control connection, and put, mput, and append transfer files from the host 
on the secondary control connection to the host on theprimary control connection. 
Third-party fi le transfers depend upon supportof the FTP protocol pasv command 
by the server on the secondary control connection. 

Storea locai fileon the remote machine. If remote - fi i e isleft unspecified, the locai 
fi lename isused after processing accordi ngto any ntrans or nmap setti ngs in naming 
the remote fi le. File transfer usesthecurrent settingsfortype, format, mode, and 

structure. 

P ri nt the name of the current worki ng di rectory on the remote machi ne. 
A synonym for bye. 

T he arguments specified aresent, verbatim, to the remote FTP server. 
A synonym for get. 

Reget acts like get, exceptthat if i oc ai -f m e existsand is smaller than remote-f m e, 
i oc ai -f i i e ispresumed to bea parti al lytransferred copy of remote-f 1 1 e and the 
transfer is conti nued from theapparent point of failure. Thiscommand isuseful 
when transferri ng very large fi les over networks that are prone to drappi ng 
connections. 

Request help from the remote FTP server. If a command- name is specified, it issupplied 
to the server as well. 

With no arguments, show status of remote machine. If f 1 1 e - name is specified, show 

status of f 1 1 e- n a me on remote machine. 

Renarne the fi le from on the remote machine, to thefileu. 

Clear reply queue. Thiscommand resynchronizes command/reply seguenti ng with 

the remote FTP server. Resynchronization may benecessary following a violation of 

the FTP protocol by the remote server. 

Restart the immedi ately following get or put at theindicated marker. On U N IX 
systems, marker isusually a byte offset i nto thefile. 
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rmdir di rectory-name 
runique 



send o c a I ■ fi 
sendport 



e [remote-fi le] 



site a r g 1 a r g 2 ... 

size f i I e- n a me 
status 

struct [struct-name] 
sunique 



system 

tenex 

trace 

type [t y p e - n a me ] 
umask [newmask] 



user user- name [password] [account] 



verbose 



? [ c o mma n d ] 



D elete a directory on the remote machine. 

Toggle stori ngof fileson thelocal system with uniquefilenames. Ifafileal ready 
existswith a nameequal to the target locai filenamefor aget or mget command, a .1 
isappended to the name. If the resulti ng namematchesanother existingfile, a .2 is 
appended to the originai name If this process conti nuesup to .99, an errar message 
isprinted, and the transfer doesnot take place. The generated uniquefilenamewill 
bereported. N otethat runique will not affect locai fi les generated from ashell 
command. The default value isoff. 
A synonym forput. 

Toggle the use of port commands. By default, ftp will attempt to use a port 
command when establishing a connection for each data transfer. The use of port 
commands can prevent delayswhen performing multi pie fi le transfers. If the port 
command fails, ftp will usethedefault data port. W hen theuseof port commands is 
disabled, no attempt will be madeto use port commandsfor each data transfer. This 
isuseful forcertain FTP implementationswhich do ignorepoRT commands but, 
in correrti y, indicatethey'vebeen accepted. 

Theargumentsspecified aresent, verbatim, to the remote FTP server asasiTE 
command. 

Return size off ne-name on remote machine. 
Show the current status of ftp. 

Set the fi le transfer structure to s t r u c t ■ n a me . By default stream structure is used. 
Toggle stori ng of fi les on remote machine under uniquefilenames. Remote FTP 
server must support ftp protocol stou command for successful completion. The 
remote server will report unique name. Default value is off. 
Show the type of operati ng system running on the remote machine. 
Set the fi le transfer type to that needed to talk to TEN EX machines. 
Toggle packet traci ng. 

Set the fi le transfer type to type- name. If no type is speci fi ed, the current typeis 
printed. The default type is network ascii. 

Set the default umask on the remote server to newmask. If newmask isomitted, the 
current umask isprinted. 

Identify yourself to the remote FTP server. I f the password isnotspecifiedandthe 
server requiresit, ftp will prompt the user for it (after disabling locai echo). If an 
account fi eld is not specified, and the FTP server requires it, the user will be 
prompted for it. If an account fi eld is specified, an account command will berelayed 
to the remote server after thelogin sequenceiscompleted if the remote server di d 
not requireit for logging in. U nless ftp isinvoked with auto-login disabled, this 
processisdoneautomatically on initial connection to the FTP server. 
Toggle verbose mode. In verbose mode, ali responsesfrom the FTP server are 
displayed to the user. In addition, if verbose ison, when a file transfer completes, 
stati sti cs regardi ng the eff i ci ency of the tran sfer are repo rted . B y def au 1 1, verbose i s 
on. 

A synonym forneip. 



Command argumentswhich haveembedded spaces may bequoted with quotation marks( 



ABORTING A FILE TRANSFER 

To abort a file transfer, use the terminal interrupt key (usuai lyC tri-C). Sending transfers will beimmediately halted. 
Receiving transfers will be halted by sending an FTP protocol abor command to the remote server, and discardi ngany 
further data received. Thespeed atwhich thisisaccomplished dependsupon the remote server's support for abor processing. 




If the remote server doesnotsupport the abor command, an ttp> promptwill not appear until the remote server has 
completed sendingtherequested file. 

The terminal interrupt key sequencewill beignored when ftp has completed any locai processing and isawaiting a reply 
from the remote server. A longdelay in thismodemay result from the abor processi ngdescribed earlier in thissection, or 
from unexpected behavior by the remote server, includi ng violations of the FT P protocol. If thedelay resultsfrom unex- 
pected remote server behavior, the locai ftp program must bekilled by hand. 



Filesspecified as argumentsto ftp commandsare processed accordi ng to thefollowing rules: 
If the filmarne - isspecified, thestdin (for reading) or stdout (for writing) isused. 

If the first character of thefilenameisj, the remainder of theargument isinterpreted asashell command. ftp then forksa 
shell, using popen 3 with theargument supplied, and reads(writes) from the stdout (stdin). If theshell command includes 
spaces, theargument must bequoted; for example, is -ìt. A particularly useful exampleof thismechanism is: dir more. 

Failing thepreceding checks, if "giobbi ng" isenabled, locai filenamesareexpanded accordi ngto the rules used in thecsh 1; 
c.f. thegiob command. If the ftp command expects a single locai file (for example, put), only the first filenamegenerated by 
the "globbing" operation isused. 

Formget commandsand get commandswith unspecified locai filenames, the locai filmarne isthe remote filename, which 
may bealtered by acase, ntrans, ornmap setti ng. The resulti ng filename maythm bealtered if runique ison. 

Formput commandsand put commandswith unspecified remote filenames, the remote filmameisthe locai filename, which 
may bealtered by an ntrans or nmap setti ng. The resulti ng filename may then bealtered by the remote server if sunique ison. 



The FTP specification specifiesmany parametersthat may affect a fi le transfer. The type may beone of ASCII, image 
(binary), ebcdic, and locai byte size (for PD P N s-lOsand PDP N s-20s mostly). ftp supports the ASC 1 1 and image typesof 
fi le transfer, plus locai byte size 8 for tenex mode transfers. 

ftp supports only the default values for the remaining file transfer parameters: mode, form, and struct. 



Thefilecontains login and initialization information used by the auto-login process. It residesin the user's home directory. 
Thefollowing tokens are recognized; they may beseparated by spaces, tabs, or newlines: 



FILE NAMING CONVENTIONS 



FILE TRANSFER PARAMETERS 



THE. netrc FILE 



machine name 



account stri n g 



default 



login name 



password stri ng 



Identify a remote machine name. The auto-login process searches the fi le for a machinetoken that 
matches the remote machi ne specified on the ftp command line or asan opm command argument. 
When a match ismade, thesubsequent tokens are processed, stoppi ng when the end of fileis 
reached or another machine or a default token is encountered. 

T hisis the sameas machi ne name except that defauit matches any name. Therecan beonly one 
default token, and it must be after ali machi ne tokens This isnormally used asdef ani t i ogi n 
anonymous password user ©si te, thereby gi vi ng theuser automatic anonymousttp login to machi nes 
not specified. This can beoverridden by using the -n flag to disable auto-login. 
Identify a user on the remote machine. If this token ispresmt, the auto-login process wi II initiatea 
login using the specified name. 

Supply a password. Ifthistoken ispresmt, the auto-login process will supply the specified stri ng if 
the remote server requires a password as part of the login process. N otethat if thistokm is present 
in the fi le for any user other than anonymous, ftp will abort the auto-login process if theisreadable 
by anyonebesides the user. 

Supply an additional account password. If thistokm is present, the auto-login process will supply 
the specified stri ng if the remote server requires an additional account password, or the auto-login 
process will initiatean acct command if itdoesnot. 
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macdef name D efine a macro. Thistoken functions like the ftp macdef command functions. A macro isdefined 

with the specified name itscontents begin with thenext li ne and continue unti I a nuli line 
(consecutivenewlinecharacters) isencountered. If a macro named init isdefined, it isautomati- 
cally executed asthelaststep in theauto-login process. 

ENVIRONMENT 

ftp utilizesthefollowing environment variables: 

home For default location of afile, if oneexists 

shell For default shell 

SEEALSO 

ftpd(8) 

HISTORY 

The ftp command appeared in BSD 4.2. 
BUGS 

Correct execution of many commands dependsupon proper behavior by the remote server. 

An errar in the treatment of carriagereturnsin the BSD 4.2 ASC I I-mode transfer codehasbeen corrected. Thiscorrection 
may result in incorrect transfersof binary fi lesto and from BSD 4.2 servers using the ASC 1 1 type Avoid thisproblem by 
usi ng the bi nary i mage type 

BSD 4.2, 30 July 1991 

f user 

f user— I denti fy processes using files 
SYNOPSIS 

f user [— a|— s] [—si gnal ] [-kmuv] fi I e ri a me ... [-] [-$ i g n a I ] [-kmuv] f il e n a me ... 
fuser [-1] 

D ESC RIFIO N 

fuser displays the PI Dsof processes using the specified files or fi le systems. In the default display mode, each filmarne is 
followed by a letter denoti ng the type of access: 



c Current directory. 

e Executablebeing run. 

f 0 pen file f isomitted in default display mode. 

r Root directory. 

m mmap 'ed fileor shared library. 



fuser returns a nonzero return codeif none of the specified files isaccessed or in case of a fatai errar. If at least one access has 
been found, fuser returns zero. 

0PTI0NS 

-a Show ali files specified on the command line. By default, only files that areaccessed by at least one process 

areshown. 

-k Kill processes accessi ng thefile U nlesschanged with -si gnal, sigkill issent. A fuser process never kills 

itself, but may kill other fuser processes. 
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FI 



u Listali known signal names. 

-m fi i e r a me specifies a file on a mounted fi le system or a block devicethat ismounted. Ali processes accessi ng 

fileson that fi le system arelisted. If a directory file is specified, it is automati cally changed to menarne/, to 
use any fi le system that might be mounted on that directory. 

-s Silent operation. -a, -u, and -v are ignored in this mode. 

-si gnai Usethe specified signal instead of sigkill when killing processes. Signalscan be specified either by name 

(forexample, -hup) or by number (for example, -1). 
-u Appendtheusernameoftheprocessownertoeach PID. 

-v Verbose mode. Processes are shown in a ps-like style. Thefields pid, user, and command aresimilarto ps. 

access shows how the processaccessesthefile. 
Reset ali options and set the signal back to sigkill. 

FILES 

/proc Location of the proc file system 

EXAMPLES 

fuser -km /home kills ali processes accessi ng the file system /home in any way. 
In this example: 

if fuser -s /dev/ttyS1; then :; else something 

fi invokes something if no other process is usi ng /dev/ttysi. 
RESTRICTIONS 

Processes accessi ng the same fi le or fi lesystem several times in thesameway are only shown once. 
AUTHOR 

Werner Al mesberger (<aimesberiadi.epfi.ch>u) 
SEEALSO 

kill(l), killall(l), ps(l), kill(2) 
Linux, 110ctoberl994 
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g++-GNU project C-H-Compiler 
SYNOPSIS 

g++ [ opti or | f i I e name ] . . . 

D ESC RIFIO N 

TheC and C -H-compilers are integrateci; g++ i s a seri pt to cali gec with options to recognizeC++. gec processes input fi les 
through oneor moreof four stages: preprocessing, compilation, assembly, and linking. This man page contai ns full 
descriptions for only C ++ specific aspeets of the compi ler, though it al so contai ns summaries of some general- purpose 
options. For a fuller explanation of the compiler, seegcc(l). 

C-H-sourcefilesuseoneof thesuffixes .c, .ce, .cxx, .cpp, or .c++; preprocessed C -H-files usethe suffix .a. 
OPTIONS 

T nere are many command-l ine options, includi ng options to control detailsof optimization, warnings, and code generation, 
which are common to both gec and g++. For full information on ali options, seegcc(l). 
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-Dmac r o 
-Dmacr o = d e f n 
-E 

-fall-virtual 



-f dollars-in-identif iers 



-felide-constructors 



Options must be separate -dr is quite different from -d -r. 

M ost-f and -w options havetwo contrary forms: -fname and -fno-name (or-wname and -wno-name). Only thenondefault 
formsareshown here. 

-c Compileor assemblethesourcefiles, but do not link. Thecompiler output isan 

object filecorrespondingto each sourcefile. 
Definemacro macrowith thestring 1 asits definiti on. 
Definemacro macro asdef n. 

Stop after the preprocessing stage; do not run thecompiler proper. The output is 
preprocessed source code, which issent to the standard output. 
Treatall possi blememberfunctionsas vi rtual, implicitly. Ali memberfunctions 
(exceptfor constructor functionsand new or delete mem ber operators) aretreated as 
virtual functionsof the class wherethey appear. 

Thisdoesnot mean that ali Calisto thesemember functionswill bemadethrough 
theinternal tableof virtual functions. U nder somecircumstances, thecompiler can 
determine that a cali to agiven virtual function can bemadedirectly; in thesecases 
the cai Is are direct in any case. 

Permittheuseof $ in identifiers. Traditional C allowed the character sto forni part 
of i denti f iers; by default, GNU C also allowsthis. However, ANSI C forbids $ in 
identifiers, and GN U C++ also forbids it by default on most platforms(though on 
some platforms it's enabled by default forGNU C++aswell). 
Usethisoption to i nstruct the com pi ler to besmarter aboutwhen itcan elide 
constructors. Withoutthisflag, GNU C++ and efront both generate effectively the 
samecodefor 
A foo (); 

A x (foo ()); // x initialized by 'foo ()', no ctor called 
A y = foo (); // cali to 'foo ()' heads to temporary, // y is initial- 
ized from the temporary. 

N otethedifference. With thisflag, GNU C++initializesy directly from the cali to 
fooo without goingthrough atemporary. 

NormallyGNU C++ al lows conversi on of enumtoint, but nottheotherway 
around. Usethisoption if you want GN U C++to allow conversion of mt to enum as 
well. 

Produce smal ler codefor templatedeclarations, by generati ng only a single copy of 
each template function whereit isdefined. To usethisoption successfully, you must 
also mark ali filesthat usetemplateswith either #pragma impiementation (the 
definition) or#pragma interface (deci arati ons). 

When your code is compi led with -fexternai-tempiates, ali template instantiati ons 
areexternal. You must arrangefor ali necessary instanti ationsto appear in the 
implementation file you can do thiswith a typedef that references each instantiation 
needed. Conversely, when you compi le usi ng the default option -f no- externai- 
tempiates, ali template instantiations are explicitly internai. 
Do not output global i niti al izations (such asC++constructorsand destructors) in 
theform used bytheGNU linker (on systemswheretheGN U linker is the standard 
method of handling them). Usethisoption when you wantto use a non-GN U 
linker, which also requiresusingthecoiiect2 program to makesure the system 
linker includes constructors and destructors (coiiect2 isincluded intheGNU CC 
distri bution.) Forsystems which must use coiiect2, thecompiler driver gec is 
confi gured to do this automati cally. 

Theseflags are used to get the com pi ler to com pi le program sfaster using heuristics. 
T hey are not on by default si nce they are only effecti ve about half the ti me. T he 
other half of the ti me programs compile more slowly (and take more memory). 



-f enum-int-equiv 



-fexternal-templates 



-f no-gnu-linker 



-f memoize-lookups-f save-memorized 




The first ti me the compi ler must build a cali to a member function (or referenceto a 
data member), it must (1) determinewhether theclass implements member 
functionsof that name; (2) resolvewhich member function to cali (which involves 
figuring out what sortsof type conversi ons need to bemade); and (3) check the 
visibility of the member function to the Caller. Ali of thisaddsup to slower 
compilation. N ormally, thesecond ti me a cali ismadeto that member function (or 
reference to that data member), it must go through the same lengthy process again. 
Thismeans that code likethis: 

cout « "This " « p << "has"<< n << " legs.\n"; 

makessixpasses through ali threesteps. By usi ng a software cache, a "hit" signifi- 
cantly reducesthiscost. U nfortunately, usi ng the cache introducesanother layer of 
mechanismswhich must beimplemented, and so incursitsown overhead. - 
fmemorize- ìookups enables the software cache 

Because access privileges (visibility) to membersand member functionsmay differ 
from onefunction contextto thenext, g++ may need to flush thecache. With the- 
fmemoize-iookups flag, the cache isflushed after every function that is compi led. The 
-fsave-memorized flag enables the same software cache, but when the compi ler 
determines that the context of the last function compiled would yield the same 
access privileges of thenext function to compi le, it preserves the cache. This is most 
helpful when defining many member functionsfor the same class: with the 
exception of member functions which are friendsof other classes, each member 
function has exactly the same access privi legesas every other, and the cache need not 
be flush ed. 

Do not make member functions inline by default merely because they aredefined 
inside the class scope. Otherwise, when you specify-o, member functions defi ned 
inside class scope are compiled inline by default; that is, you don't need to add 
iniine in front of the member function name 

C onsider the declaration int foo;(). In C++, thismeans that the function foo takes 
no arguments. In AN SI C, this is declared int foo(void) ;. W ith the flag -fno- 
strict-prototype, declaring functions with no arguments is equi valentto declaring 
its argument list to beuntyped, that is, int foo(); isequivalentto saying int foo 
(...) ; .-tnonnuii-objects. N ormally, GNU C ++makes conservative assumptions 
aboutobjectsreached through references. Forexample, thecompiler must check that 
a isnot nuli in code likethefollowing: 

obj &a = g () ; 
a.f (2); 

C hecking that references of this so rt have non-nuli values requires extra code, 
however, and it isunnecessary for many programs. You can use -fnonnuii-oojects to 
omitthechecksfor nuli, if your program doesn't require the default checking. 
Theseoptions control the recognition of the signature and sigof constructsfor 
speci fying abstract types. By default, these constructs are not recognized. 
The incorporation of user-defined free store management into C++ has made 
assignmenttothisan anachronism. Therefore, by default GNU C++treats the type 
of this in a member function of class X to bex *const. In other words, it is il legai to 
assign to thiswithin a class member function. However, for backwards compati bil- 
ity, you can invoketheold behaviorbyusing-ftius-is-variabie. 
Produce debugging information in the operati ng system's native format (for D BX or 
SDBorDWARF). GDB also can work with this debugging information. On most 
systems that useD BX format, -g enables use of extra debugging information that 
only GD B can use 

U nlike most other C compi lers, GN U CC allowsyou to use-g with -0. The 
shortcutstaken by optimized code may occasionally produce surprising results: some 
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-Idi r 
-Ldi r 
-11 i br ar y 

-nostdinc 

-nostdinc++ 
-0 

-o f i I e 
-S 

-traditional 



-Urna c r o 
-Wall 



-Wenum-clash 
-Woverloaded- virtual 



variablesyou declared may not exist at ali; flow of control may briefly movewhere 
youdid not expect it; some statements may not beexecuted becausetheycompute 
Constant results or the r valueswerealready at hand; some statements may execute in 
different places becausethey were moved out of loops. 

N evertheless, it proves possi bleto debug optimized output. This makes it reasonable 

to use the opti mizerfor programsthat might havebugs. 

Append directory di r to the list of directoriessearched for include fi les. 

Add directorydi r to the list of directories to besearched for-i. 

Usethelibrary named i i brary when linking. (C++programsoften require -ig++ for 

successful linking.) 

Do not search the standard system directories for header fi les. Only the directories 
you havespecified with -i options(and thecurrent directory, if appropriate) are 
searched. 

Do not search for header files in the standard directories specific to C++, but do stili 
search theother standard directories. (Thisoption isused when building iibg++.) 
Optimize. Optimizing compilation takes somewhat moretime, and a lot more 
memory for a largefunction. 
Place output in f Me f i i e. 

Stop after thestageof compilation proper; do not assemble. The output isan 
assembler code fi le for each nonassembler input fi le speci fi ed. 
Atterri pt to support some aspectsof traditional C compi lers. Specificai ly, for both C 
and C++programs: 

In the preprocessor, comments convertito nothi ng at ali, ratherthan to aspace This 
al lows traditional token concatenation. 

In the preprocessor, macro argumentsarerecognized within string constants in a 
macro definition (and their values are stringified, though without additi onal quote 
marks, when they appear in such a context). The preprocessor always considersa 
string Constant to end atanewline 

The preprocessor does not predefi ne the macro stdc when you use -traditional, but 
stili predefi nesGNuc (sincetheGN U extensionsindicated byGNuc are not affected by 
-traditional). If you need to write header files that work differently dependi ngon 
whether -traditional isin use, by testi ng both of these predefi ned macrosyou can 
disti nguish four situati ons: GNU C, traditional GN U C, other AN SI C compi lers, 
and other old C compi lers. 

In the preprocessor, comments convertito nothi ng at ali, ratherthan to aspace This 
al lows traditional token concatenation. 

String "constants" are not necessari ly Constant; they arestored in writable space, and 
identical looking constants are allocated separately. For C ++ programs only (not C ), 
-traditional has one additional effect: assignmentto this is permitted. Thisisthe 
same as the effect of -f this-is-variabie. 
Undefine macro macro. 

Issuewarningsfor condì tions that pertain to usagethat werecommend avoidingand 
that webelieveis easy to avoid, even in conjunction with macros. 
Warn when converting between different enumeration types. 
In a derived class, the definitions of virtual functionsmust match the type signature 
of avirtual function declared in thebase class. Use thisoption to requestwarnings 
when a derived class declares a function that may bean erroneousattemptto define 
avirtual function; that is, warn when afunction with thesamenameasa virtual 
function in thebase class, but with a type signature that doesn't match anyvirtual 
functionsfromthebaseclass. 
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-Wtemplate-debugging 

-w 
+eN 



When using tempi ates in a C++ program, warn if debugging isnot yet fully 
available. 

Inhibitall warning messages. 

Control how virtual function defi nitions are used, in afashion compati blewith 

efront 1 .x. 



PRAGMAS 

Two #pragma di recti ves are supported for GN U C++, to permit using the sameheader fi le for two purposes: asa definition of 
interfacesto agiven object class, and as the full definition of thecontentsof that object class 

#pragma interface Usethis directive in headerfilesthat defineobject classes, to savespace in mostof 

theobject filesthat use those classes. Normally, locai copiesof certain information 
(backup copies of inline member functions, debugging information, and the internai 
tablesthat implement virtual functions) must be kept in each object fi le that 
includes class definitions. You can use this pragmato avoid such duplication. When 
a header filecontaining#pragma interface isincluded in a compilation, this auxiliary 
information will not begenerated (unlessthemain input sourcefile itself uses 
#pragma impiementation). I nstead, the object files wi II contain referencesto be 
resolved at link time. 

Usethis pragma in a main input fi le, when you want full output from included 
header files to begenerated (and made globally visi ble). The included header file, in 
turn, should use#pragma interface. Backup copiesof inline member functions, 
debugging information, and the internai tablesused to implement virtual functions 
areali generated in implementation files 

If you use#pragma implementation with no argument, it appliesto an include fi le 
with thesamebasenameasyour sourcefile; forexample, in aiiciass.ee, #pragma 

implementation by itself ÌS equivalent tO #pragma implementation "allclass.h". Use 

the stri ng argument if you want a single implementation fileto include code from 
multiple header files. 

Thereisno way to split up thecontentsof a single header fi lei nto multiple 
implementation files. 



#pragma implementation 

#pragma implementation lobjects.h! 



FILES 



file.h 

file.i 

file file.C 

file.ee 

file.cxx 

file.s 

file.o 

a.out 

TMPDIR/cc 

LIBDIR/cpp 

LIBDIR/cdplus 

LIBDIR/collect 

LIBDIR/libgcc.a 

/lib/crt[01n] .0 

LIBDIR/ccrtO 

/lib/libc.a 



C header (preprocessor) file 

Preprocessed C source 

C++ sourcefile 

C++ source fi le 

C++ source fi le 

Assembly language file 

Object file 

Link edited output 

Temporary files 

Preprocessor 

Compiler 

Linker front end needed on somemachines 
GCC subroutine library 
Start-up routine 

Additional start-up routineforC++ 
Standard C library; seemtroO) 
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/usr/inciude Standard directory for#inciude files 

LiBDiR/inciude Standard gcc directory for#inciude files 

i_iBDiR/g++-inciude Additional g-H-directory for #inciude 

LIBD IR isusually /usr/local/lib/machine/version. 

tmpdir comes from the environment vari able tmpdir (default /usr/tmp if available, else / tmp). 
SEEALSO 

gcc(l), cpp(l), as(l), ld(l), gdb(l), adb(l), dbx(l), sdb(l), gcc, cpp, as, ld, and gdb entries in info. 

U sing and P orti ng G N U CC (forversion 2.0), Richard M . Stallman;TheC Preprocessor, Richard M . Stallman; Debugging 
with GDB: theGN U Source-Level Debugger, Richard M . Stallman and Roland H . Pesch; U sing as theGN U Assembler, Dean 
Elsner, Jay Fenlason and friends; gld: theGN U linker, Steve Cham beri ai n and Roland Pesch. 

BUGS 

Forinstructionson howto reportbugs, seetheGCC manual. 
COPYING 

Copyright © 1991, 1992, 1993 Free Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim 
copiesof this manual provided the copyright noticeand this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof this manual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof this manual into another language, under the above conditions 
for modifi ed versi ons, except that this permission notice may beincluded in translationsapproved by the Free Software 
Foundation instead of in theoriginal English. 

AUTHORS 

SeetheGNU CC M anual for the contri butorsto GNU CC. 
GNU Tools, 30 Aprii 1993 
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g3topbm— C onvert a G roup 3 fax file into a portable bitmap 
SYNOPSIS 

g3topbm [ -kludge] [ -reversebits] [ -stretch] [ g 3 f i I e ] 

DESCRIPTION 

Readsa Group 3 fax fi le as input. Produces a portable bitmap as output. 
0PTI0NS 

-kiudge Tells g3topbm to ignore thefirst few linesof the fi le; sometimes fax fi leshave some junk at thebeginning. 

-reversebits Tells g3topbm tO interpret bitS least -signif icant first, instead Of the default most-significant first. 

Apparently, somefaxmodemsdo itonewayand othersdo ittheotherway. If you getawholebunch of 
"bad codeword" messages, try using thisflag. 
-stretch Tellsg3topbm to stretch the image vertically by dupli catingeach row. This is for the low-quality transmis- 

sion mode. 



Ali flags can be abbrevi ated to their shortest unique prefix. 
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REFERENCES 

The standard for Group 3 fax isdefined in CCITT Recommendation T.4. 

BUGS 

Probably. 

SEEALSO 

pbmtog3(l), pbm(5) 

AUTHOR 

Copyright© 1989 by Paul Haeberli (pauiemanray.sgi.com) 
2 October 1989 
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gawk— Pattern scanning and processing language 
SYNOPSIS 

gawk [ POSIX or GNU style options ] -f program-fi I e [ — ] file ... 
gawk [ POSIX or GNU style options ] [ — ] p r o g r a m- 1 e x t file ... 

D ESC RIFIO N 

gawk istheGN U Project'simplementation of theawk programmi ng language. It conformsto the defi nition of the language 
in the 1003.2 Command Language and U ti I iti es Standard. Thisversion in turn isbased on thedescription in TheAWK 
Programming Language, by Aho, Kernighan, and Weinberger, with theadditional features defi ned in theSystem V Release4 
version of awk. gawk also providessomeGN U-specific extensions. 

The command line consists of options to gawk itself, theawk program text (if not supplied via the -f or --file options), and 
valuesto bemadeavailablein theARGC andARGv predefined awk variables. 

OPTIONS 

gawk options may beeither the tradì ti onal one-letter options, or theGN U -style long options. Traditi onal style options start 
with a single-, whileGN U long options start with — . GNU -style long options are provided for both GN U -speci fi c features 
and for mandated features. Other implementationsof theawk language are likely to only accept the tradì ti onal one-letter 
options. 

Following the standard, gawk-specific options are supplied viaargumentsto the-woption. M ulti pi e -w options may be 
supplied, or multiple arguments may be supplied together if they areseparated by commas, or enclosed in quotesand 
separated by whitespace. Caseisignored in arguments to the-w option. Each -woption hasacorrespondingGN U -style long 
option, asdetailed below. Arguments to GNU -style long options are either joi ned with the option by an = sign, with no 
intervening spaces, or they may be provided in thenext command-lineargument. 

gawk accepts the following options: 

-f fs, — fieid-separator=f s Usefs for the input field separator (the value of the Fs-predefined variable). 

-v v a r =v a i , — assign=var =va i Assign thevalueva! , to the variable va r , beforeexecution of the program begins. Such 

variable values are availableto the begin block of an awk program, 
-f program-fi i e, Readtheawk program source from the fi le pr og r a m- f i e , i nstead of from the first 

— f±ie=pr ogr a m- f i i e command-li ne argument. M ulti pie -f (or —file) options may beused. 

-mf=NNN, -mr=NNN Set various memory limitsto the value nnn. The f flag sets the maximum number of fields, 

and the r flag sets the maximum record size. Thesetwo flagsand the-m option are from the 

AT&T Bell Labsresearch version of awk. They are ignored bygawk, sincegawk hasno 

predefined limits. 
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-W compat, —compat 

-W copyleft, -W copyright, 
— copyleft, —copyright 
-W help, -W usage 
— help, —usage 
-W lint, — lint 

-W posix, — posix 



-W source=pr og r a m- 1 e x t , 
— source=pr ogr am- 1 ext 



-W version, --version 



Run in compati bility mode. In compatibility mode, gawk behaves i denti cai lyto awk; noneof 
the G N U -speci fic extensions are recognized. See "G N U Extensions," later in this manual 
page, for more information. 

P ri nt the short version of theGN U copyright information messageon the error output. 

Print a relatively short summary of the available options on the error output. Per the G N U 
CodingStandards, these options cause an immediate, successful exit. 
Provide warningsabout constructsthat aredubiousor nonportableto other awk i implemen- 
tati ons. 

Thisturnson compatibility mode, with thefollowing additional restri ctions:\x escape 
sequences are not recognized. 

Thesynonym fune for the keyword function isnot recognized. 
The operatore** and **= cannot beused in placeof ' and •=. 
Use program- text asawk program source code. This option allows the easy intermixingof 
library functions(used via the -f and —file options) with source code entered on the 
command line. It isintended primari ly for medium to largeawk programsused in shell 
scripts. 

The-w source=form of this option usestherestof thecommand-lineargumentfor 
program- 1 ext ; no other optionsto -wwill be recognized in thesameargument. 
Print version information for this parti cular copy of gawk on the error output. Thisisuseful 
mainly for knowing if thecurrent copy of gawk on your system is up-to-date with respect to 
whatever the Free Software Foundation isdistributing. PertheGNU CodingStandards, 
these options cause an immediate, successful exit. 

Signal the end of options. Thisisuseful to allow further argumentsto the awk program itself 
to start with a-. This is mainly for co n si sten cy with theargument-parsing convention used 
by most other programs. 

In compatibility mode any other options are flagged asillegal, but areotherwiseignored. In normal operation, aslongas 
program text hasbeen supplied, unknown options are passed on to the awk program in theARGv array for processing. Thisis 
parti cui ari y useful for runningawk programs via the#i executable interpreter mechanism. 

awk PROGRAM EXECUTION 

An awk program consistsof asequenceof pattern-action statementsand optional function definitions: 

pattern { action st at ement s } 

function name (par a me t er list) { stat ement s } 

gawk first reads the program source from theprogram-file(s) if specified, from argumentsto -w source=, orfrom thefirst 
nonoption argument on the command line. The -f and -w source= options may beused multi pie ti meson the command 
line gawk will read the program text asif ali theprogram-filesand command-li ne source texts had been concatenated 
together. Thisisuseful for building librariesof awk functions, without havingto include them in each new awk program that 
usesthem. Italso provides the abi lity to mix library functionswith command-line programs 

Theenvironment variableAWKPATH specifiesasearch path to usewhen fi nding source fi lesnamed with the -f option. If this 
variabledoes not exist, the default path is . :/usr/iib/awk:/usr/iocai/iib/awk. 

If afilenamegiven tothe-f option containsa/ character, no path search isperformed. 

gawk executesawk programs in thefollowing order. First, ali variable assignments specified via the -v option areperformed. 
N ext, gawk compi les the program into an internai form. Then, gawk executesthecodein the begin block(s) (if any), and then 
proceedsto read each filenamed in theARGv array. If thereareno fi lesnamed on the command line, gawk reads the standard 
input. 

If afilenameon the command linehastheform v a r =v a i , it istreated asa variable assignment. The variable «a r will be 
assigned thevaluevai . (This happens after any begin block(s) nave been run.) Command-linevariableassignment ismost 
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useful for dynamically assi gning vai uesto the vari ablesawk usesto control how input isbroken into fieldsand records. It is 
also useful for controlli ng state if multi pie passes are needed over a single data file 

If thevalueof a parti cular element of argv isempty (""), gawk skipsover it. 

Foreach line in the input, gawk teststo seeif it matchesany pattern in theawk program. For each pattern that the line 
matches, theassociated action isexecuted. Thepatternsaretested in theorder they occur in the program. 

Finally, after ali theinput isexhausted, gawk executes the code i n theEND block(s) (if any). 
VARIABLES AND FIELDS 

awk vari ables are dynamic; they come into existencewhen they are first used. Their values are either floating-point numbers 
or strings, or both, dependi ng upon how they are used. awk also hasone-dimensional arrays; arrayswith multi pie di mensions 
may besimulated. Several predefi ned variables are set as a program runs; thesewill bedescribed as needed and summarized 
in the "Built-ln Variables" subsection. 

FIELDS 

Aseach input lineisread, gawk splits the line into fields, usi ng thevalueof the fs variableasthefield separator. If fs isa 
single eh aracter, fields are separated by thatcharacter. Otherwise, fs isexpected to bea full regular expressi on. In the special 
case that fs is a si ngle blank, fields are separated by runsof blanks or tabs. N ote that thevalueof ignorecase (seethe 
following) will also affect how fields are split when fs isa regular expression. 

If the fieldwidths vari able is set to a space separated list of numbers, each field isexpected to havefixed width, and gawk will 
split up the record usi ng the speci fi ed widths. Thevalueof fs isignored. Assi gning a new valueto fs overridestheuseof 
fieldwidths, and restores the default behavior. 

Each field in theinput line may bereferenced by itsposition, $1, $2, and so on. $0 is the whole li ne Thevalueof a field may 
beassigned to aswell. Fields need not bereferenced by constante 

n =5 

print $n 

printsthefifth field in theinput line The vari able nf is setto the total number of fields in theinput line. 

Referencesto nonexistent fields (that is, fields after $nf) produce the null-string. H owever, assigningto a nonexistent field 
(forexample, $(nf+2) = 5) will increase thevalueof nf, create any intervening fields with the nuli stri ng as thei r value, and 
cause the valueof $0 to berecomputed, with the fields being separated by thevalueof ofs. Referencesto negati ve-numbered 
fields cause a fatai errar. 

BUILT-IN VARIABLES 

awk's bui It-i n vari ables are the followi ng: 

argc T he number of command-li ne arguments(does not include opti onsto gawk, or the program source). 

argind The index in argv of thecurrent fi le being processed. 

argv Array of command-li ne arguments. Thearray isindexed from 0 to argc - 1. Dynamically changing the 

contents of argv can control the fi les used for data. 
convfmt Theconversion format for numbers, "%.6g", by default. 

environ An array contai ni ng the values of thecurrent environment. Thearray isindexed by theenvironment 

variables, each element bei ng the valueof that variable (forexample, environ["home m ] might be/u/amoid). 

Changing this array does not affect theenvironment seen by programswhich gawk spawns vi a redirection 

orthesystemo function. (Thismay changein a future versi on of gawk.) 
errno If a system error occurs either doing a redirection for getiine, during a read for getiine, or during a 

cioseo, then errno will contai n a stri ng descri bi ng the error. 
fieldwidths A whitespace-separated list of fieldwidths. When set, gawk parses the input into fields off ixed width, 

instead of usi ng the value of theFs variableasthefield separator. The fixed field width faci li ty is stili 

experimental; expect thesemanticsto changeasgawk evolves over ti me. 
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FNR 
FS 

IGNORECASE 



NF 
NR 

OFMT 
OFS 

ORS 
RS 



RSTART 

RLENGTH 

SUBSEP 



Thenameof thecurrent input file. If no files are specified on thecommand line, thevalueof filename is-. 
However, filename isundefined inside theBEGiN block. 
Theinput record number in thecurrent input file. 
The input field separator, a blank by default. 

Controls the case-sensi ti vi ty of ali regular expressi on operations. If ignorecase has a nonzero value, then 

pattern matching in rules, field splittingwith fs, regular expression matchingwith " and r, and the 

gsub( ), index( ), match( ), spiitf ),and sub( ) predefined functionswill ali ignorecasewhen doing regular 

expression operations. Thus, if ignorecase isnot equal to zero, /aB/ matchesall of the stringsab, aB, Ab, 

and ab. Aswith ali awk variables, theinitial value of ignorecase iszero, so ali regular expression operations 

are normally case- sensi ti ve. 

The number of fi elds in thecurrent input record. 

The total number of input recordsseen so far. 

Theoutput format fornumbers, "%.6g", by default. 

The output field separator, a blank by default. 

Theoutput record separator, by default a newline. 

Theinput record separator, by default a newline. rs isexceptional in thatonly the first character of its 

stri ng value isused for separating records. (Thiswill probably changein a future releaseof gawk.) If rs isset 

to the nuli string, then records are separated by blank lines. W hen rs isset to the nuli string, then the 

newline character alwaysacts asa field separator, in addition to whatever value fs may have. 

The index of thefirst character matched by match(); 0 if no match. 

Thelength of the string matched bymatch(); -1 if no match. 

T he character used to separate multiple subscripts i n array elements, by default nB34. 



ARRAYS 

Arraysaresubscripted with an expression between square brackets. If the expression isan expression I i st (e x p r , ex pr ...) 
then the array subscript is a string consisti ngof the concatenation of the (string) value of each expression, separated by the 
value of the subsep variable. Thisfacility isused to simulate multi ply dimensioned arrays. For example, 



i = "A" ; j 
x[i, j, k] = 



"B" ; k = "C" 
"hello, world\n" 



assigns the string hello, worid\n to theelement of the array xwhich isindexed by the string "A\034B\034C". Ali arraysin awk 
are associative, that is indexed by string values. 

The special operator in may beused in an if orwhiie statement to see if an array hasan index consisti ng of a particular 
value: 

if (vai in array) 
print array[val] 

If the array has multi pi e subscripts, use (i, j )±n array. 

The in construct may also beused in a for loop to iterate over ali the elements of an array. 

An element may bedeleted from an array usi ng the deiete statement. The deiete statement may also beused to delete the 
enti re contents of an array. 

VARIABLE TYPING AND CONVERSILI N 

Variables and fi elds may befloating-point numbers, or strings, or both. H ow thevalueof a variable isinterpreted depends 
upon itscontext. If used in a numeric expression, it will betreated asa number; if used asa string, itwill betreated asa 
string. 

To force a variable to betreated asa number, add 0 to it; to force itto betreated asa string, concatenate it with the nuli 
string. 




When a stri ng must beconverted to a number, theconversion isaccomplished usi ng atof(3). A number isconverted to a 
stri ng by usingthevalueof convfmt as a format stri ngfor sprintf(3), with the numeri cvalueof the vari ableas the argument. 
H owever, even though ali numbersin awk are floating-point, integrai valuesarealwaysconverted asintegers. Thus, given this: 

CONVFMT = "%2.2f" 
a =12 
b =a"" 

thevariableb hasastring valueof 12 and not 12.00. 

gawk performscomparisonsasfollows: If two variablesarenumeric, they arecompared numerically. If onevalueis numeri c 
and theother hasastring valuethat isa"numeric string," then comparisonsarealso done numerically. Otherwise, the 
numeric value isconverted to a string and a string comparison is performed. Two stri ngs arecompared, of course, asstrings. 
Accordingto the standard, even if two stri ngs are numeric strings, a numeric comparison is performed. H owever, thisis 
clearly incorrect, and gawk doesnot do this. 

Uninitialized variables have the numeric value 0 and the string value "" (the nuli, or empty, string). 
PATTERN S AND ACTION S 

awk isa line-oriented language. The pattern comes first, and then the action. Action statementsareenclosed in and .br. 

E ither the pattern may bemissing, or the action may bemissing, but, of course, not both. If the pattern ismissing, the action 

will beexecuted for every single li ne of input. A missing action isequivalent to 

{ print } 

which printstheentireline. 

Commentsbegin with the# character, and continue unti I the end of the line. Blank lines may beused to separate state- 
ments. N ormai ly, a statement endswith a newline, however, thisis not the case for lines ending in a ,, {, ?, : , &&, or ; | . Lines 
ending in do or else also have thei r statements automati cally conti nued on thefollowing line. In other cases, a linecan be 
conti nued by ending it with a \, in which case the newline will beignored. 

M ulti pie statements may be put on one line by separati ng them with a semicolon. This appliesto both the statements within 
the action part of a pattern-action pair (the usuai case), and to the pattern-action statements themselves. 

PATTERN S 

awk pattern s m ay be 0 n e of th e f ol I owi n g: 

BEGIN 
END 

/regni a r expressi on / 

relational expression 

pattern && pattern 

pattern j j pattern 

pattern ? pattern : pattern 

(pattern) 

! pattern 

pat t er ni, pat t er n2 

begin and end are two special kindsof patternsthat are not tested against the input. The action partsof ali begin patternsare 
merged as if ali the statements had been written in a single begin block. They areexecuted beforeany of the input isread. 
Similarly, ali the end blocks are merged, and executed when ali the input isexhausted (or when an exit statement is 
executed). begin and end patternscannot becombined with other patternsin pattern expressions. begin and end patterns 
cannot have missing action parts 

For /regui ar expression / patterns, theassociated statement is executed for each input linethat matchestheregular 
expression. Regular expressionsarethesameasthosein egrep(l), and aresummarized asfollows: 
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A rei a t i o n a i ex pressi on may use any of the operators defined later in the section on actions. These general ly test whether 
certain fields match certain regular expressions. 

The&&, ||, and ! operators are logicai and, logicai or, and logicai not, respectively, asin C. They do short-ci rcuit evaluation, 
also as in C, and areused for combining more primitive pattern expressions Asin most languages, parentheses may beused 
to changetheorder of evaluation. 

The?: operator islikethesameoperator in C. If the first pattern istrue, then the pattern used for testi ng isthesecond 
pattern; otherwise, it isthethird. Only oneof thesecond and third patterns isevaluated. 

The pa 1 1 e r ni , pa 1 1 e r n 2 form of an expression iscalled a range pattern. It matchesall input records starti ngwith a linethat 
matchespat terni, and conti nuing until a record that matches pat t e r n 2 , inclusive It does not combine with any other sort of 
pattern expression. 

REGULAR EXPRESSIONS 

Regular expressions are the extended kind found in egrep. They arecomposed of charactersasfollows: 

c Matches the non-meta-characterc. 

\c M atches the literal character c. 

M atches any character except newline 

M atches the beginning of a line or a string. 
$ M atches the end of a li ne or a string. 

[abc. . . ] Character class, matches any of thecharactersabc. . .. 

pa oc. . . ] Negated character class, matches any character except abc. . . and newline 
r 1 ; r 2 Alternation: matches either ri or r 2 . 

r 1 r 2 Concatenation: matchesri, and then r2. 

r+ M atches one or more rs. 

r* M atches zero or more rs. 

r? Matches zero or one rs. 

(r ) Grouping: matches r . 

Theescape sequences that are valid in string constants are also legai in regular expressions. 
ACTIONS 

Action statementsareenclosed in braces, { and >. Action statementsconsistof the usuai assignment, conditional, and looping 
statements found in most languages. Theoperators, control statements, and input/output statementsavailablearepatterned 
after those in C. 

OPERATORS 

Theoperators in awk, in order of increasi ng precedence, are 

=+=-= Assignment. Both absolute assignment (va r = vai ne) and operator-assignment (the other forms) are 

*= /= %= "= supported. 

?: TheC conditional expression. Thishastheformexpri ? e x p r 2 : e x p r 3 .Ifexpri istrue, thevalueof the 

expression i s e x p r 2 ; otherwise, it i s e x p r 3 . Only oneof e x p r 2 and expr 3 isevaluated. 
Il Logicai or. 

&& Logicai and. 

"!" Regular expression match, negated match. N OTE: Do not use a Constant regular expression (/foo/) to the 

left of a " or !". 0 nly use one on theright side. The expression /foo/ " exp hasthesamemeaningas (<$a 
" /foo/) " exp ) . T hisisusually not what was intended. 

< >, <=>= Theregular relational operators. 

biank String concatenation. 

+- Addition and subtraction. 
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*/% M ultiplication, division, and modulus. 

+-! U nary plus, unary minus, and logicai negation. 

Exponentiation (** may also beused, and **= fortheassignmentoperator). 
++ — Increment and decrement, both prefix and postfix. 

$ Field reference 

CONTROL STATEMENTS 

The control statementsareasfollows: 

if (condition) statement [ else statement ] 
while (condition) statement 
do statement while (condition) 
for (expM; expr2; expr3) statement 
for (var in array) statementbreak 
continue 

delete array[index] 
delete array 
exit [ expression ] 
{ statements } 

I/O STATEMENTS 

The input/output statements are asfollows: 

ciose(f i e n a me ) C losefile (or pipe, see paragraph following this list), 

getiine Set $0 from next input record; set nf, nr, fnr. 

getiine <f m e Set $0 from next record of f il e ; set nf. 

getiine var Set var from next input record; set nf, fnr. 

getiine var <f i i e Set var from next record Off il e . 

next Stop processing the current input record. The next input record isread and processing starts 

overwith the first pattern intheawk program. If theend of the input data isreached, the 
end block(s), if any, are executed. 

next file Stop processing the current input file. The next input record read comesfrom the next 

input file filename isupdated, fnr is reset to 1, and processing starts overwith thefirst 
pattern in the awk program. If the end of the input data is reached, the end block(s), if any, 
are executed. 

print P ri nts the current record. 

print e x p r - 1 i s t Prints expressions. Each expression isseparated by the valueof the ofs vari able. The output 

record isterminated with the valueof the ors variable. 
print e x p r - 1 i s t >f i i e P ri nts expressions on f i i e . Each expression is separated by the value of the ofs variable The 

output record isterminated with the valueof the ors variable. 
printt fmt, expr-iist Format and print. 

printf fmt, expr-iist >f i i e Format and print on f m e . 

system(cmd- line) Execute the command c md- 1 i ne, and return the exit status. (This may not beavailableon - 

POSIX systems.) 

Other input/output redi rections are also allowed. For print and printf, »f i i e appends output to thef ile, while | command 
writeson a pipe. In a si mi lar fashion, command j getiine pipesinto getiine. The getiine command will return 0 on end of 
file, and -1 on an errar. 

THE printf STATEMENT 

The awk versionsof the printf statement and sprintfQ function accept the following conversion specification formats: 

%c An ASCII character. If theargument used for%c isnumeric, itistreated asacharacterand printed. 

Otherwise, theargument isassumed to bea stri ng, and the only first character of that stri ng i s printed. 
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%d A decimai number(theintegerpart). 

%i J ust like %d. 

%e A floating-point number of theform [-]d.ddddddE[+-]dd. 

%f A floating-point number of theform [-jddd.dddddd. 

%g Usee or f conversion, whichever is shorter, with nonsignificantzerossuppressed. 

%o An unsigned octal number (again, an integer). 

%s A character string. 

%x An unsigned hexadecimal number (an integer). 

%x Like %x, butusingABCDEF instead of abcdef. 

%% A si ngle % character; no argument isconverted. 

There are optional, additional parametersthat may liebetween the % and the control letter: 

Theexpression should beleft-justified within itsfield. 
wi dth Thefield should bepadded to thiswidth. If the number hasa leading zero, then thefield will bepadded 

with zeros. Otherwise, it ispadded with blanks. Thisapplieseven to thenonnumeric output formats. 
. p r e c A number indicati ng the maximum width of stringsor digitsto theright of the deci mal point. 

Thedynamicwi dth and p r e c capabilitiesof theC printf() routinesaresupported. A * in place ofeither the wi dth or pr ec 
specifi cations will cause the r values to betaken from theargument list to printf or sprintf(). 

SPECIAL FILENAMES 

When doing I/O redirection from either print or printf into a file, or viagetiine from a fi le, gawk recognizescertain special 
fi lenames internally. T hesefilenames allow access to open file descri ptors inherited from gawk's parent process (usuai ly the 
shell). Other special filenames provide access information about the running gawk process. The filenames are 

/dev/pid Reading thisfile retums the process I D of the current process, in decimai, terminated with a newline. 

/dev/ppid Reading thisfile retums the parent process ID of the current process, in decimai, terminated with a 
newline. 

/dev/pgrpid Reading thisfile retums the process group ID of the current process, in decimai, terminated with a 
newline. 

/dev/user Reading thisfile retums a si ngle record terminated with a newline. The fi elds are separated with blanks. $1 
isthevalueof thegetuid(2) system cali, $2 isthevalueof thegeteuid(2) system cali, $3 isthevalueof the 
getgid(2) system cali, and $4 isthevalueof the getegìd( 2) system cali. If there are any additional fi elds, 
they are the group IDsreturned by getgroups(2). M ultiplegroupsmay not besupported on ali systems. 

/dev/stdin T he standard input. 

/dev/stdout The standard output. 

/dev/stdem Thestandard errar output. 

/dev/fd/n T he file associated with theopen fi le descri ptorn. 

T hese are particularly useful for errar messages. For example, you could use 

print "You blew it!" > " /dev/stderr" 

whereasyou would otherwise haveto use 

print "You blew it!" j "cat 1>&2" 

These filenames may also beused on thecommand lineto namedatafiles. 

NUMERIC FUNCTIONS 

awk hasthefollowing predefined arithmetic functions: 
atan2(y , x ) Retums the arctangent of y/x in radians. 
cos(expr ) Retums the cosine in radians. 
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exp(expr) T he exponential function. 

int(expr) Truncatesto i nteger. 

iog(expr ) The naturai logarithm function. 

rand() Returnsa random number between 0 and 1. 

sin(expr) Returns the si ne i n radians. 

sqrt(expr) T he square root function. 

srand(expr) Useexpr as a new seed for the random number generator. If no ex pr isprovided, thetimeof day will be 
used. The return valueis the previous seed for the random number generator. 

STRING FUNCTIONS 

awk hasthefollowing predefined string functions 



t) 



gsub(r , 

index(s , t ) 
lengthfs ) 
match (s , r ) 



split (s , a , r ) 



sprintf (f mt , 
sub(r , s , t ) 
substrfs , i , 
tolower(st r ) 

toupper(st r ) 



expr- list) 



For each substri ng matching theregular expression r in the string t , substitute the string s, 

and return the number of substitutions. If t isnot supplied, use$e. 

Returns the index of the string t in the stri ngs, ore if t isnot present. 

Returns the length of the string s , orthelength of $o if s isnot supplied. 

Returns the position in s where theregular expression r occurs, oro if u isnot present, and 

setsthevaluesof rstart and rlength. 

Spi its the stri ng s into thearray a on theregular expression r , and returnsthe number of 
fidds. If r isomitted, Fsisused instead. Thearray a i s ci eared first. 
P ri nts expr- 1 i st accordi ng tof mt , and returnsthe resul ti ng string. 
Just like gsub(), but only the first matching substri ngisreplaced. 
Returns the n-character substri ng of s starti ng ati . If n isomitted, the rest of s isused. 
Returnsa copy of the string s t r , with ali the uppercase characters i n s t r translated to their 
correspondi ng lowercase counterparts. N onalphabetic characters are left unchanged. 
Returnsa copy of the string st r, with ali the lowercase characters in str translated to their 
correspondi ng uppercase counterparts. N onalphabetic characters are left unchanged. 



TIME FUNCTIONS 

Sinceoneof theprimary usesof awk programsis processing logfilesthat contai n ti me stamp informati on, gawk provi des the 
f o 1 1 owi n g two f un cti o n s f o r obtai n i ng ti m e stam ps an d f orm atti n g them . 

Returns the current ti me of day as the number of secondssincethe Epoch (M idnight UTC , 
January 1, 1970 on systems). 

Formatsti mestamp according to the speci fi cation int ormat . Thet i mestamp should beof the 
sameform asreturned by systimeo. If t i mestamp ismissing, the current timeof day isused. 
See the specificati on forthestmimeo function in C fortheformatconversionsthatare 
guaranteed to beavailable. A public-domain version of strftime(3) and a man page for it are 
shipped with gawk; if that version wasusedto build gawk.then ali of theconversions 
described in that man page are availableto gawk. 



systime() 



strftime(f ormat , ti mestamp) 



STRING CONSTANTS 

String constants in awk are sequencesof characters enclosed between doublé quotes( 
sequencesarerecognized, asin C.Theseare 

\\ A I iterai backslash. 

\a T he "alert" character; usually the ASC 1 1 BEL character. 

\b Backspace. 

\t Formfeed. 

\n Newline. 



. W ithin strings, certain escape 
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\r C arri age return. 

\t H orizontal tab. 

\v V erti cai tab. 

\xhex di gi ts Thecharacter represented by the stri ngof hexadecimal digits following the\x. Asin C, ali following 

hexadecimal digits are considered part of the escape sequence. (Thisfeatureshould teli ussomethingabout 
language design by committee.) Forexample, "uib" is the ASC 1 1 ESC (escape) character. 

\ddd Thecharacter represented bythel-, 2-, or 3-digit sequence of octal digits. Forexample, "\033" isthe 

ASCII ESC (escape) character. 

u The I iterai character c. 



T he escape sequencesmay also beused inside Constant regularexpressions (forexample, /[\\t\f\n\r\v]/ matcheswhitespace 
characters). 

FUNCTIONS 

Functionsin awk are defined asfollows: 

f u n c t i o n n a me ( p a r a me t e r list) { s t a t e me n t s } 

Functionsareexecuted when called from within the action partsof regular pattern-action statements. Actual parameters 
supplied in thefunction cali areused to instantiate the formai parameters declared in thefunction. Arraysarepassed by 
reference, other vari ables are passed by value. 

Functionswerenot ori gi nally part of the awk language, so the provision for locai variablesisrather clumsy: They are declared 
as extra parameters in theparameter list. The convention isto separate locai variablesfrom real parameters by extra spacesin 
theparameter list. Forexample 

function f(p, q, a, b) { # a & b are locai 
} 

label { ... ; f(1, 2) ; ... } 

Theleft parenthesis in a function cali isrequired to immediately follow thefunction name, without any intervening 
whitespace. Thisisto avoid asyntactic ambiguity with theconcatenation operator. This restri ction doesnot apply to the 
built-in functionslisted earlier. 

Functionsmay cali each other and may berecursive. Function parameters used as locai vari ables are initialized to the nuli 
stri ng and the number zero upon function invocation. 

The word fune may beused in place of function. 

EXAMPLES 

Print and sort the login names of ali users: 

BEGIN { FS = ":" } 
{ print $1 j "sort" } 

Count linesin afile 

{ nlines++ } 

END { print nlines } 

Precede each lineby itsnumber in thefile: 

{ print FNR, $0 } 

Concatenate and line number (a vari ation on atheme): 

{ print NR, $0 } 




SEEALSO 

egrep(l), getpid(2), getppid(2), getpgrp(2), getuid(2), geteuid(2), getgid(2), getegid(2), get -groups(2) 

TheAWK Programming Language, Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger, Addison-Wesley, 1988. ISBN 
0-201-07981-X. 

TheGAWK M anual, Edition 0.15, published by the Free Software Foundation, 1993. 
PO SIX COMPATIBILITÀ 

A primary goal for gawk is compati bili ty with the standard, aswell aswith the latest versi on of awk. To thisend, gawk 
incorporatesthefollowing user-visi blefeatures that arenot described in the awk book, but arepart of awk in System V 
Release4, and are in the standard. 

The-v option for assigningvariablesbefore program execution startsisnew. The book indi cates that command-l ine vari able 
assignment happenswhen awk would otherwiseopen theargument asafile, which is after theBEGiN block isexecuted. 
H owever, in earlier implementations, when such an assignment appeared beforeany filenames, the assignment would happen 
beforetheBEGiN block wasrun. Applications carne to depend on this"feature." When awk waschanged to match its 
documentation, thisoption wasadded to accommodateapplicationsthat depended upon theold behavior. (Thisfeaturewas 
agreed on by both the AT&T and GN U developers.) 

T he -w option for im pi ementati on-specific features isfrom the standard. 

When processing arguments, gawk uses the special option — to signal the end of arguments. In compati bi li ty mode, it will 
warn about, but otherwise ignore, undefined options. In normal operation, such arguments are passed on to the awk program 
for itto process. 

The awk book doesnot define the return valueof srando. The System V Release4 version of awk (and the standard) hasit 
return theseed it wasusing, to allow keepingtrack of random number sequences. Therefore srando in gawk also returns its 
currentseed. 

Other new features are: the use of multiple -f options (from M KS awk); the environ array; the\a, and w escape sequences 
(doneoriginally in gawk and fed back into AT&T 's version); thetoiowero and touppero built-in functions(from AT&T); 
and theC conversi on specificationsin printf (done first in AT&T's version). 

GNU EXTENSIONS 

gawk hassomeextensionsto awk. They are described in this section. Ali the extensions described herecan bedisabled by 
invokinggawk with the -w compat option. 

T he following features of gawk arenot available in awk: 

The \x escape sequence. 

Thesystimeo and strftimeo functions. 

The special filenames availablefor I/O redirection are not recognized. 

TheARGiND and errno variables are not special. 

TheiGNORECASE variableand its side effects. 

T he fieldwidths variable and fixed width field spi itti ng. 

N o path search isperformed for filesnamed via the -f option. Therefore, theAWKPATH environment variable is not special. 
T he use of next file to abandon processi ng of the current i nput fi le. 
T he use of deiete array to delete the entire contents of an array. 

The awk book does not define the return valueof the cioseo function. gawk'scioseo returns the vai ue from fciose(3), or 
pciose(3), when dosi ng a fi le or pipe, respectively. 

When gawk isinvoked with the-w compat option, if the fs argumentto the-F option ist, then fs will beset to thetab 
character. Sincethis is a rather ugly special case it isnot the default behavior. This behavior also does not occur if -wposix 
hasbeen specified. 




Parti: U ser Commands 



H ISTORIO AL FEATURES 

Therearetwo featuresof histori cai awk implementationsthat gawk supports. First, it is possi bleto cali theiengtho built-in 
function notonlywith noargument, but even without parentheseslThus, this: 

a = length 

is the same as either of these: 

a = length() 
a = length($0) 

Thisfeatureismarked as "deprecateci" in the standard, and gawk wi II issueawarningabout itsuseif -w unt isspecified on 
thecommand line 

T he other feature is the use of either the conti nue or the break statements outside the body of a whiie, f or, or do loop. 
Traditional awk implementations havetreated such usageasequivalent to thenext statement, gawk wi 1 1 support thisusage 
if -w compat hasbeen specified. 

EN VIRO NMENT VARIABLES 

If posixly_correct exists in theenvironment, then gawk behaves exactly as if - -posix had been specified on thecommand 
line If --ìint hasbeen specified, gawk wi 1 1 issueawarning messageto thiseffect. 

BUGS 

The-Foption isnot necessary given the command-li ne variable assi gnment feature; it remai nsonly for backwardscompat- 
ibility. 

If your system actually has support for /dev/fd and theassociated /dev/stdin, /dev/stdout, and /dev/stderr files, you may get 
different output from gawk than you would get on a system without those files. When gawk interpretsthese files internally, it 
synchronizes output to the standard output with output to /dev/stdout, whileon a system with those files, the output is 
actually to different open files. C aveat emptor. 

VERSION INFORMATION 

Thisman page documents gawk, version 2.15. 

Starti ng with the 2.15 version of gawk, the-c, -v, -c, -d, -a, and -e optionsof the 2.11 version areno longer recognized. This 
factwill not even bedocumented in themanual page for thenext major version. 

AUTHORS 

Theoriginal version of awk wasdesigned and implemented by Alfred Aho, Peter Weinberger, and Brian Kernighan ofAT&T 
Bell Labs. Brian Kernighan continuesto maintain and enhanceit. 

Paul Rubin and Jay Fenlason, of the Free Software Foundation, wrotegawk, to becompatiblewith theoriginal version of awk 
distri buted in theseventh edition.John Woods contri buted a number of bugfixes. DavidTrueman, with contri butions from 
Arnold Robbins, madegawk compatiblewith thenew version of awk. Arnold Robbins isthe current maintainer. 

The initial DOS portwasdoneby Conrad Kwok and Scott G arti nkle. Scott Deifik isthe current DOS maintainer. Pat 
Rankin did theportto VM S, and M ichal Jaegermann did theportto the Atari ST. Theportto OS/2 wasdoneby Kai Uwe 
Rommel, with contri butions and helpfrom Darrel Hankerson. 

BUG REPORTS 

If you find a bug in gawk, pleasesend electronic mail to 

bug -gnu -utils@prep . ai.mit . edu , 



with a copy to arnoid@gnu.ai.mit.edu. Please include your operati ng system and its revision, the version of gawk, whatC 
compileryou used to compile it, and a test program and data that are assmall as possi blefor reproducingthe problem. 




Beforesendinga bug report, pleasedo two things. First, verify thatyou havethelatest versi on of gawk. M any bugs (usually 
subtleones) arefixed at each release, and if yoursisout of date, theproblem may already havebeen solved. Second, please 
read thisman page and thereferencemanual carefully to besurethatwhatyou think isa bug really is, instead of just aquirk 
in thelanguage. 

ACKNOWLEDGMENTS 

Brian Kernighan of Bell Labs provi ded valuableassistanceduringtesting and debugging. 
Wethank him. 

FreeSoftwareFoundation, 24 Novemberl994 



gcal 

gcai— D isplaysmonth/year calendar sheets, eternai holiday listsforjulian and Gregorian years, and fixed datewarning 
I i sts— al I i n a vari ety of ways. 

SYNOPSIS 

gcal [[ Option... ][%Date ][9File... ]] [ Command ] 

D ESC RIFIO N 

gcai isaprogram si milar the standard calendar programsBSD- 1 cai 1 and calendar. 

gcai displays Gregorian calendars, Julian calendars(beforeSeptember 1752). 

If gcai isstarted without any options or commands, a calendar of the current month is displayed. 

If the calendar of a definite year iswanted, theyear must befully specified. For example, gcai 94 displays a year calendar of 
theyear94, not of theyear 1994. 

If two argumentsaregiven in the command part, the first argument denotes the month and the second argument denotes the 
year. In case any i Negai commands are given runni ng gcai, the program wi II use internai defaults. 

The Gregorian Reformation isassumed to haveoccurred in 1752 on the 3rd of September. Ten daysfollowing that date 
were elimi nated by the reformation, so the calendar for that month is a bit unusual. 

MORE PROGRAM INFORMATION 

You get more program information if you start gcai asfollows: 

gcal -h gcal -? gcal -help 
resp. , 

gcal -hh gcal -?? gcal -long-help[=ARG] j [=?] gcal -usage[=ARG] j [=?] 

A hypertext file gcai. info containing detailed online information should beavailable, which you can inspectusingyour 
GNU Infobrowser. 

COPYRIGHT 

gcai copyright © 1994, 1995, 1996 by Thomas Esken. This software doesn't claim completeness, correctness, or usability. 
On principle, I will not be liableforany damages or losses {i mplicit or explicit), which result from usi ng or handling my 
software. If you use this software, you agree without anyexception to this agreement, which bindsyou legai ly. 

gcai isfree software and distri buted under thetermsof theGN U General Public License; published by the F ree Software 
Foundation; version 2 or (atyour option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposalsfor contractwork, and so forth are welcome! 
If you likethistool, l'd appreciatea postcard from you! 

Enjoy it =8") 
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AUTHOR 

Thomas Esken (esken@uni-muenster.de) 

lm H agenfeld 84 

D -48147 M uenster; Germany 

Phone: +49 251 232585 

SEEALSO 

cal(l), calendar(l) 
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gcc,g++-GNU project C and C++Compiler (v2.7) 
SYNOPSIS 

gcc [ opti or j fi I e ri a me ] . . . 
g++ [ opti or j fi I e n a me ] . . . 

WARNING 

Theinformation in thisman page i san extract from the full documentati on of theGN U C compi ler and islimited to the 
meaning of theoptions. 

Thisman pageis not kept up-to-date except when volunteerswant to maintain it. If you find adiscrepancy between the man 
page and the software, please check the info file, which istheauthoritativedocumentation. 

If wefind thatthethings in this man pagethat areout of date cause significant confusion or compiai nts, wewill stop 
distributing the man page The alternative, updating the man page when we update the info file, is impossi blebecause the 
restof thework of maintaining GNU CC leavesus no timeforthat. TheGN U project regards man pagesas obsolete and 
should notletthem taketimeaway from otherthings. 

For complete and current documentati on, refer to the info fi le gcc orthemanual Using and Porting GN U CC (for version 
2.0). Both are made from theTexinfo sourcefilegcc.texinfo. 

DESCRIPTION 

TheC and C-H-compilersareintegrated. Both process input filesthrough oneor moreof four stages: preprocessing, 
compilation, assembly, and linking. Sourcefilenamesuffixesidentifythesourcelanguage, but which nameyou use for the 
compi ler governs default assumptions: 

gcc Assumes preprocessed (.i) filesareC and assumesC-style linking. 

g++ Assumes preprocessed (.i) fi les are C++ and assumes C++-style linking. 

Suffixesof sourcefilenames indicatethelanguageand kind of processing to bedone: 



c 


C source; preprocess, compile, assemble 


C 


C++ source preprocess, compile, assemble 


ce 


C++source preprocess, compile, assemble 


cxx 


C++ source preprocess, compile, assemble 


m 


Objective-C source; preprocess, compile assemble 


i 


Preprocessed C; compile, assemble 


ii 


Preprocessed C++; compile, assemble 


s 


Assembler source; assemble 



gcc g++ 



.s Assembler sou ree; preprocess, assemble 

.h Preprocessorfile; notusually named on command line 

Fileswith other suffixesare passed to thelinker. Common cases include 

.0 Object file 
.a Archive file 

Linking is always the last stage un lessyou useoneof the-c, -s, or -e optionsto avoid it (or unless compilation errorsstop 
thewholeprocess). For the link stage, ali .0 filescorrespondingto sourcefiles, -1 librari es, unrecognized filenames (including 
named .0 object fi les, and .a archi ves) are passed to thelinker in command-lineorder. 

OPTIONS 

Options must be separate -dr isquitedifferentfrom -a -r. 

Most-f and -w options havetwo contrary forms: -fname and -fno-name (or-wname and -wno-name). Onlythenondefaultforms 
are shown here 

Hereisasummaryof ali theoptions, grouped by type. Explanationsarein thefollowi ng sections. 
Overall Options 

-c -S -E -0 file -pipe -v -x I anguage 



Language Options 

-ansi 

-f dollars-in-identif iers 
-f no-asm 

-f signed-bitf ields 
-f un sig ned-bit fields 
-traditional 

W arni ng Options 

-f syntax-only 
-w -W -Wall 
-Wcast-qual 
-Wconversion 
-Wf ormat 
-Winline 

-Wnested-externs 

-Wpointer-arith 

-Wshadow 

-Wtemplate-debugging 
-Wuninitialized 

Debugging Options 

-a -dletters -fpretend-f loat -g -i 
save- temps -print-f ile-name=l i b n 

Optimization Options 

-f caller-saves 
-f delayed-branch 
-f fast-math 
-f f orce-mem 



-f all-virtual 
-f enum-int-equiv 
-f no-builtin 
-f signed-char 
-f unsigned-char 
-traditional-cpp 

-pedantic 

-Wagg regate- return 

-Wchar-subscript 

-Wenum-clash 

-Wid-clash-len 

-Wmissing-prototypes 

-Wno-impdrt 

-Wredundant-decls 

-Wstrict-prdtotypes 

-Wtraditional 

-Wunused 



-f cond-mismatch 

-f external-templates 

-f no-strict-prdtotype 

-f this-is-variable 

-fwritable-strings 

-trigraphs 

-pedantic-errors 

-Wcast-align 

-Wcomment 

-Werrdr 

-Wimplicit 

-Wmissing-declarations 

-Wparentheses 

-Wreturn-type 

-Wswitch 

-Wtrigraphs 

-Wwrite-strings 



il evel -geoff -gxeoff -gxcoff+ -gdwarf -gdwarf+ -gstabs -gstabs+ -ggdb -p -pg 
ry -print-libgcc-file-name - print-prog-name=pr og r a m 



-f cse-f ollow-j umps 
-f elide-constructors 
-f float-store 
-f inline-f unctions 



-f cse-skip-blocks 
-f expensive-optimizations 
-f force-addr 
-fkeep-inline-f unctions 
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-f memorize-lookups -f no-def ault-inline -f no-def er-pop 

-f no-f unction-cse -fno-inline -f no-peephole 

-fomit-f rame-pointer -f rerun-cse-af ter-loop -f schedule-insns 

-f schedule-insns2 -f strength-reduce -f thread-j umps 

-f unroll-all-loops -f unroll-loops -0 -02 

Preprocessor Options 

-Aassertion -C -dD -dM -dN -Dma cro[=defn ] -E -H- idiraf ter d i r -include file -imacros file -ipref ix file- 
iwithprefix dir -M -MD -MM -MMD -nostdinc -P -Urna ero -undef 

Assembler Option 

-Wa.opt i ori 

Linker Options 

-llibrary -nostartf iles -nostdlib -static -shared -symbolic -Xlinkerno pt i o n -Wl,o p t i o n -u symbol 

Directory Options 

-Bpr ef i x -Idi r -I- -Ldi r 

Target Options 

-b machine -V versi o n 

C onfiguration-D ependent 0 ptions 

M 680x0 Options 

-m68000-m68020 -m68020-40-m68030-m68040-m68881 -mbitfield -mc68000 -mc68020 -mfpa -mnobitfield -mrtd -mshort -msoft- 
float 

VAX Options 

-mg -mgnu -munix 

SPARC Options 

-mepilogue -mfpu -mhard-f loat -mno-fpu -mno-epilogue -msoft-float -msparclite -mv8 -msupersparc -mcypress 

Convex Options 

-margeount -mei -mc2 -mnoargeount 

AM D29K Options 

-m29000-m29050 -mbw -mdw -mkernel-registers -mlarge -mnbw -mnodw -msmall -mstack-check -muser-registers 

M 88K Options 

-m88000 -m88100 -m88110 -mbig-pic 

-mcheck-zero-division -mhandle-large-shif t 

-midentif y- revision -mno-check-zero-division 

-mno-ocs-debug-inf o -mno-oes-f rame-position 

-mno-optimize-arg-area -mno-serialize-volatile 

-mno-underscores -mocs-debug-inf o 

-mocs-f rame-position -moptimize-arg-area 

-mserialize-volatile -mshort-data-num 

-msvr3 -msvr4 -mtrap-large-shif t 

-muse-div-inst ruction -mversion-03. 00 
-mwarn-passed-struets 
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-mf p-arg-in-f pregs 
-mhc-struct- return 



-mf p-arg-in-gregs 

-min-line-mul 

-mnohc-struct-return 



-mmips-as 
-mgpopt 

-msoft-f loat 



-mint64 -mlong64 
-mgas 

-mno-gpopt 
-mhard-f loat 



-mrnames 
-mstats 



-mabicalls 



RS6000 Options 

-mfp-in-toc -mno-f op-in-toc 

RT Options 

-mcall-lib-mul 
-mf ull-f p-blocks 
-mminimum-f p-blocks 

M I PS Options 

-mcpu=cpu type -mips2 -mips3 
-mlonglongl 28 
-mno-rnames 

-mno-stats -mmemcpy -mno-memcpy -mno-mips-tf ile 
-mmips-tf ile 
-mno-abicalls -mhalf-pic -mno-half-pic -G num -nocpp 

Ì386 Options 

-m486 -mno-486 -msoft-float-mno-fp-ret-in-387 
H PPA Options 

-mpa- rise- 1-0 -mpa- rise- 1-1 -mkernel -mshared-libs- mno-shared-libs-mlong-calls-mdisable-fpregs-mdisable- 
indexing -mtrailing- colon 

i960 Options 
-mcpu -type 
-mnumerics 

-mno-leaf -procedures 
-meomplex-addr 
-mno-code-align 
-mic3 .0-compat 
-mstrict-align 
-mno-old-align 

DEC Alpha Options 

-mfp-regs -mno-fp-regs -mno-sof t-f loat -msoft-float 

System V Options 

-G -Qy -Qn -YP,paths -Ym.dir 

Code-Generation Options 

-f call-saved-r eg -fcall-used- 
reg -ffixed-reg -finhibit- 
size-directive -fnonnull- 
objects -fno-common -fno-ident 
-f no-gnu-linker -f pcc-struct- 
return -fpic -fPIC -freg- 
struct- return -f shared-data - 
fshort-enums -f short-doublé - 
fvolatile -fvolatile-global - 
fverbose-asm 



-msoft-float 

-mtail-call 

-mno-complex-addr 

-mic-compat 

-masm-compat 

-mno-strict-align 



-mleaf-procedures 

-mno-tail-call 

-mcode-align 

-mic2 .0-compat 

-mintel-asm 

-mold-align 
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OVERALL OPTIONS 

-x i anguage Specify explicitly the i anguage for the followi ng i nput fi les (rather than choosing a default based on the 
fi lename suffix). Thisoption appliesto ali followi ng input fi les unti I thenext -x option. Possi blevaluesof 

anguage aree, objective-c, c-header, c++, epp-output, assembler, and assembler-with-cpp. 

-x none Turn off any specification of a language, so that subsequent filesarehandled accordi ngto their fi lename 

suffixes(asthey areif -x hasnot been used at ali). 

If you want only some of the four stages(preprocess, compile, assemble, link), you can use-x (or fi lename suffixes) to teli gec 
whereto start, and oneof the options -c, -s, or -e to say wheregee isto stop. N ote that some combinations (for example, -x 
epp-output -e) instruct gec to do nothing at ali. 

-c Compile or assemble the source fi les, but do not link. The compiler output isan object file corresponding 

to each source fi le. 

By default, gec makes the object fi lename for a source file by replacing the suffix .c, .i, .s, and so on, with 
.0. U se -o to select another name. 

gec ignoresany unrecognized input fi les (those that do not requi re compilation or assembly) with the -e 
option. 

-s Stop after the stage of compilation proper; do not assemble. The output isan assembler code fi le for each 

nonassembler input fi le specif ied. 

By default, gec makes the assembler fi lename for a source file by replacing the suffix .c, .i, and so on, with 

.s. Use-o to select another name. 

gec ignoresany input filesthatdon't requi re compilation. 
-e Stop after the preprocessing stage; do not run the compiler proper. The output ispreprocessed source 

code, which is sent to the standard output. 

gec ignores input filesthat don't require preprocessing, 
-o file Place output in file f i i e. Thisapplies regardlessto whatever sort of output gec is produci ng, whether it be 

an executablefile, an object file, an assembler fi le, or preprocessed C code. 

Si nce only one output fi le can be specif ied, itdoesnotmakesenseto use-owhen compi ling more than 

oneinput file unlessyou are produci ngan executable fi le as output. 

If you do not specify -o, the default isto put an executablefile in a.out, the object fi le for source .suffi x in 

source .o, its assembler fi le in s o u r c e . s, and ali preprocessed C sourceon standard output, 
-v Print (on standard error output) the commands executed to run the stages of compilation. Also printthe 

version number of the compiler driver program and of the preprocessor and the compiler proper. 
-pipe Usepipes rather than temporary filesfor communication between the vari ous stages of compilation. This 

fai Isto work on some systemswhere the assembler cannot read from a pipe; but theGN U assembler has 

no trouble. 

LANGUAGE OPTIONS 

Thefollowing options control thedialect ofC that the compiler accepts: 

-ansi Support ali AN SI standard C programs. 

Thisturnsoff certain featuresof GN U C that are incompatiblewith ANSI C, such astheasm, 
iniine, and typeof keywords, and predefi ned macrossuch asunix and vax that identify thetype 
of system you are usi ng. It also enablestheundesirableand rarely used AN SI trigraph feature, 
and disallows $ aspart of identifiers. The alternate keywords __asm_, __extension_, 
__iniine_, and __typeof„ continue to work despite-ansi. You would not want to usethem 
in an ANSI C program, of course, but it isuseful to putthem in header filesthat might be 
included in compilationsdonewith -ansi. Alternate predefined macrossuch as__unix_ and 
__vax_ are also available, with orwithout-ansi. 

The-ansi option does not cause non-AN SI programsto berejected gratuitously. For that, - 
pedantic isrequired in addition to -ansi. 
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The preprocessor predefinesa macro __strict_ansi_ when you use the -ansi option. Some 

headerfilesmay noticethis macro and refrain from declaring certain functionsor defining 

certain macrosthattheAN SI standard doesn't cali for; thisisto avoid interferi ng with any 

programsthat might usethesenamesfor otherthings. 
-fno-asm Do not recognize asm, iniine, or typeof as a keyword. T hese words may then beused as 

identifiers. You can use__asm_, __iniine_, and __typeof_ instead. -ansi implies -fno-asm. 
-fno-buiitin Don't recognize built-in functionsthat do not begin with two leadingunderscores. Currently, 

thefunctionsaffected i nclude _exit, abort, abs, alloca, cos, exit, fabs, labs, memcmp, memcpy, 

sin, sqrt, strcmp, strcpy.and strlen. 

The -ansi option prevents alloca and_exit from being built-in functions. 
-fno-strict-prototype Treat a function declaration with no arguments, such asmt food ;, asC would treat it— as 
saying nothing about thenumber of arguments ortheir types (C++ only). N ormally, such a 
declaration in C++meansthat the function foo takes no arguments. 

-trigraphs SupportANSI C trigraphs. T he -ansi option implies -trigraphs. 

-traditionai Attempt to support some aspects of traditional C compilers. Fordetails, seetheGNU C 

M anual; the duplicate list herehasbeen deleted so that wewon't get compiai nts when it isout 
of date. 

But one note about C ++programs only (not C ). -traditionai has one additional effect for 
C ++: assignment to this is permitted. T his is the same as the effect of -t ttus-is-variabie. 
-traditionai-cpp Attemptto support some aspects of traditionai C preprocessors. This includesthe itemsthat 

specificali menti on the preprocessor previ ously, but noneof theother effectsof -traditionai. 

-fdollars-in-identifiers Permit the use Of $ in identifiers (C -H-Only). YOU can alSO use -fno-dollars-in-identifierstO 

explicitly prohibit useof $. (GNU C++allows$ by default on some target systemsbut not 
others.) 

-fenum-int-equiv Permit implicit conversion of int to enumerati on types (C++ only). N ormally GN U C++ 

allows conversion of enumto int, but nottheotherway around. 
-texternai-tempiates Produce smaller code for template declarations, by generati ng only a single copy of each 

template function whereit isdefined (C++ only). To usethisoption successfully, you must also 

markall fi les that use templates with either#pragma impiementation (the definition) or#pragma 

interface (declarations). 

When your codeiscompiled with -fexternai-tempiates, ali template instantiations are external. 
You must arrangefor ali necessary instanti ationsto appear in theimplementation file you can 
do this with a typedef that references each instanti ation needed. Conversely, when you compile 
usi ng the default option -fno-externai-tempiates, ali template instantiationsareexplicitly 
internai. 

-faii-virtuai T reat al I possiblememberfunctionsasvirtual, implicitly. Ali member functions (except for 

constructor functions and new or delete member operators) aretreated asvirtual functions of 
the class wherethey appear. This does not mean that ali Calisto these member functions wi II be 
madethrough the internai tableof virtual functions. U nder somecircumstances, the compi ler 
can determinethat a cali to agiven virtual function can be m ade di recti y; in these cases, the 
cai Is are direct in any case 

-fcond-mismatch Allow conditional expressionswith mismatched types in thesecond and third arguments The 

valueof such an expression isvoid. 

-fthis-is-variabie Permit assignment to this (C++only). The incorporation of user-defined f ree sto re manage- 

ment into C ++ has made assignment to this an anachronism. Therefore, by default it is invali d 
to assign to thiswithin a class member function. H owever, for backwardscompatibility, you 
can makeit valid with -fthis-is-variabie. 

-funsigned-char Let the type char beunsigned, like unsigned char. 

Each kind of machine has a default for what char should be. It iseither like unsigned char by 
default or like signed char by default. 



Parti: U ser Commands 



-f signed-char 



-f signed-bitf ields 
-f unsigned-bitf ields 
-fno-signed-bitf ields 

-f no-unsigned-bitf ields 
-fwritable-strings 



I deal ly, a portable program should alwaysusesigned char or unsigned char when itdependson 
the signedness of an object. But many programs have been written to use plain char and expect 
itto besigned, or expect itto beunsigned, dependingon the machinesthey were written for. 
Thisoption, and its inverse, letsyou makesuch a program work with the opposite default. 
Thetypechar is always a distinct typefrom each of signed char and unsigned char, even though 
its behavior is always just likeoneof those two. 
Let thetypechar besigned, like signed char. 

N otethat thisisequivalentto -fno-unsigned-char, which isthenegativeform of -funsigned- 

char. Likewise, -fno-signed-char isequivalent tO -f unsigned-char. 

Theseoptions control whethera bitfield is si gned orunsigned, when declared with no explicit 
or unsigned qualifier. 

By default, such a bitfield is signed, becausethis is consistenti T he basic i nteger types such as 

int 

signed are signed types. 

H owever, when you specify -traditionai, bitfields are ali unsigned no matter what. 
Store string constants i n the w ri tabi e data segment and don't uniquize them. T his is for 
compati bility with old programs which assume they can writeinto string constants. -tradi- 
tionai also hasthis effect. 

Writing into string constants isa very bad idea; constants should be Constant. 

PREPROCESSOR OPTIONS 

Theseoptions control theC preprocessor, which isrun on each C source fi le before actual compilation. 

If you use the -e option, gcc does nothingexcept preprocessing. Some of theseoptions makesenseonlytogether with -e 
becausethey cause the preprocessor output to beunsuitable for actual compilation. 

-include file Processf i i e as input before processing the regular input file. In effect, thecontentsof f i e 

arecompiled first. Any-D and -uoptionson thecommand lineare always processed before 
-include file, regardless of the order in which they are written. Ali the -include and -imacros 
options are processed in theorder in which they are written. 

-imacros file Processf i i e as i nput, discardi ng the resulti ng output, before processing the regular i nput fi le. 

Because the output generated from f i i e isdiscarded, the only effect of -imacros file isto make 
themacrosdefined in fi i e available for use in themain input. The preprocessor evaluatesany 
-D and -u options on thecommand li ne before processing -imacros file, regardless of theorder 
in which they are written. Ali the -include and -imacros options are processed in theorder in 
which they are written. 

-idiratter dir Add the directory di r to thesecond include path. Thedirectorieson thesecond include path 

are searched when aheaderfileisnotfound in any of thedirectories in themain include path 

(theonethat -i addsto). 
-ipretix prefix Specify p r e f i x as the prefix for subsequent -iwithpref ix options. 

-iwithpretix di r Add a di rectory to thesecond include path. The di rectory'snameis madeby concatenati ng 

prefix and di r , wherepr ef i x was specified previ ously with -ipretix. 
-nostdinc Do not search the standard system di rectories for header files. Only thedirectories you have 

specified with -i options (and the current directory, if appropriate) are searched. 

By using both -nostdinc and -i-, you can limit the i nclude fi le search fileto only those 

di rectories you specify explicitly. 
-nostdinc++ Do not search for header files in theC-K-specific standard directories, but do stili search the 

other standard directories. (Thisoption isused when building iibg++.) 
-undet D o not predefineany nonstandard macros(including architecture flags). 

-e RunonlytheC preprocessor. Preprocessai I the C source files specified and output the resultsto 

standard output orto the specified output file, 
-c Teli the preprocessor notto discard comments. U sed with the-E option. 
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-p Teli the preprocessor notto generate #iine commands. U sed with the -e option. 

-m [-mg] Teli the preprocessor to output a mie suitable for make describingthedependenciesof each 

object file. For each sourcefile, the preprocessor outputsonemake -rul e whose target isthe 
object fi lename for that source file and whose dependencies are ali the files that have been 
included with #inciude. Thisrulemay bea single line or may becontinued with \-newlineif it 
is long. The list ofrulesisprinted on standard output instead of the preprocessed C program. 
-m implies -e. 

-mg saysto treat missing header filesasgenerated files and assume they live in the same directory 

as the sourcefile. It must bespecified in addition to -m. 
-mm [-mg] Like-M buttheoutput mentionsonlytheuser header files included with #inciude " file \ 

System header files included with #inciude < file >areomitted. 
-md Like-M butthedependency information iswritten to files with namesmadeby replacing .0 

with .d attheend of the output fi lenames. Thisisin addition to compili ng the fi le as specified; 

-md does not inhi bit ordì nary compilation theway -m does. 

TheM ach utility md can beused to merge the .d fi lesi nto a single dependency fi le suitable for 

usi ng with the make command. 
-mmd Like-MD except mention only user header files, not system header files. 

-h Printthenameof each header file used, in addition to other normal activiti es. 

-Aquest i on (answer ) Assert the answer a ns we r forqjestion, in caseit istested with a preprocessor conditional such as 

#if #q u e s t i on (answer ). -A- disables the standard asserti ons that normally describe the target 

machine. 

-Aquestion (answer ) Assert the answer a ns we r for q ues t i o n , in case it is tested with a preprocessor conditional such as 
#if # q u e s t i 0 n ( answer ). -A-disables the standard assertions that normally describe the target 
machine. 

-Dmacro Definemacro macr 0 with the stri ng 1 asits defini ti on. 

-Dmacro=def n Definemacro macr 0 asdef n. Ali instancesof -d on the command line are processed beforeany 

-u opti ons. 

-umacro U ndefinemacro macro. -u opti ons are evaluated after ali -d opti ons, but beforeany -include and 

-imacros Options. 

-dM Teli the preprocessor to output only a list of the macro definitions that are in effect attheend 

of preprocessing. Used with the -e option. 
-dD Teli the preprocessor to passali macro definitions into the output, in their proper sequencein 

therest of the output. 

-dN Like-dDexceptthatthemacroargumentsandcontentsareomitted. Only#define name is 

included in theoutput. 

ASSEMBLERÒ FIO N 

-wa.opt i on Pass opti on asan option to the assembler. If opti on contai nscom mas, it is split into multiple 



options at the commas. 
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These options come into play when the compi ler links object fi lesi nto an executable output file. They aremeaninglessif the 
compiler is not doing a link step. 

0 b j ect-f i i e - name A fi lename that does not end in a speci al recognized suffix isconsidered to namean object file 

or library. (0 bject files are disti nguished from libraries by the linker accordi ng to the fi le 
contents.) If gcc does a link step, these object files are used as inputto the linker. 

-il i brary Use the library named i i brary when linking. 

The linker searches a standard list of di rectories for the library, which is actually a fi le named 
ìib library .a. T he linker then usesthisfileasif it had been specified precisely by name. 
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-lobjc 

-nostartf iles 
-nostdlib 



-shared 



-symbolic 



-Xlinker option 



-Wl, option 
-u s y mbo 



Thedirectories searched include sa/eral standard system directories plusany thatyou specify 
with -L. 

Normally, thefilesfound thisway are library files— archi ve f iles whosemembers are object fi les. 
The linker handles an archivefile by scanning through it for members that define symbols that 
haveso far been referenced but not defined. H owever, if the linker fi ndsan ordinary object file 
rather than a library, the object fi le islinked in the usuai fashion. T he only differencebetween 
usi ng an -1 option and specifying afilenameisthat-l surroundsi i b r a r y with iib and .a and 
searches several directories. 

You need this special case of the -1 option in order to link an ObjectiveC program. 
Do not use the standard system startup fileswhen linking. The standard librariesareused 
normally. 

Don't use the standard system librariesand startup fileswhen linking. 0 nly the fi les you specify 
will bepassed to the linker. 

On systems that su pport dynamic linking, this prevents linking with the shared libraries. On 
other systems, this option has no effect. 

Produce a shared object whi eh can then belinked with other objectsto form an executable. 
0 nly a few systems support this option. 

Bind referencesto global symbols when building a shared object. Warn about any unresolved 
references(unlessoverridden by the link editor option -xiinker -z -xiinker defs). Only a few 
systems support this opti on. 

Pass option asan option to the linker. You can use this to supply system-specific linker options 
whichGNU CC does not know how to recognize. 

If you want to passan option that takesan argument, you must use -xiinker twice once for the 
option and once for the argument. Forexample, to pass-assert definitions, you mustwrite- 

Xlinker -assert -Xiinker definitions. 1 1 does not WOrk tO write -Xiinker "-assert 

definitions", because this passes the enti re stri ng as a single argument, whi eh isnot what the 
linker expeets. 

Pass option asan option to thelinker. If option contai nscom mas, it issplit into multiple 
options at the commas. 

Pretend the symbol symbol isundefined, to force linking of library modulesto define it. You 
can use-u multipletimeswith different symbols to force loadingof additional library modules. 



DIRECTORY OPTIONS 

T hese options specify directoriesto search for header files, for librarie, and for partsof the compi ler: 
-idi r Append directory di r to the list of directories searched for i nclude fi les. 

-i- Any directories you specify with -i options beforethe-i- option are searched only for the case 

of #inciude "file"; they are not searched for «include <f i i e >. 

If additional directories are specified with -i options after the-i-, these directories are searched 
forali #inciude di recti ves. (Ordì nari ly ali -i directoriesareused thisway.) 
In addition, the-i- option inhibits the use of the current directory (wherethecurrent input file 
camefrom) as the first search di rectory for «include ■ file ".Thereisnowaytooverridethis 
effect of -i-. W ith -i. you can specify searching the di rectory that was current when the 
compi ler was i nvoked. T hat is not exactly the same as what the preprocessor does by default, 
but it isoften sati sfactory. 

-i- does not inhi bit the use of the standard system directories for header files. Thus, -i- and 
-nostdinc are independent. 
-Ldir Add directory di r to the list of directories to be searched for -1. 

-Bpref i x This option specifies where to find theexecutables, libraries, and data fi les of the compi ler itself. 

Thecompiler driver program runsoneormoreof thesubprogramscpp, ed (or, forC++, 
ed plus), as, and id. 1 1 tries p r e f i x asa prefix for each program it triesto run, both with and 

without ma c h I ne / versi o n /. 
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For each subprogram to berun, the compi ler driver first tri es the -b prefix, if any. If that name 
is not found, or if -b was not specified, the driver tri estwo standard prefixes, which are/usr/ 
iib/gcc/ and /usr/iocai/iib/gcc-iit>/. If neither of those results in afilenamethatisfound, the 
compi ler driver searchesfortheunmodified program name, using the di rectories specified in 
your path environment variable. 

Theruntimesupportfileiibgcc.a isalso searched for using the -b prefix, if needed. If it isnot 
found there, thetwo standard prefixes ( precedi ng paragraph) aretried, and that i sali. The file is 
left out of the link if it isnot found by those means. M ost of the ti me, on most machines, 
ìibgcc.a isnot actually necessary. 

You can get asimilar resultfrom the environment variable gcc_exec_prefix; if it isdefined, its 
valueisused asa prefix in thesameway. If both the-B option and theGcc_EXEc_PREFix variable 
arepresent, the-B option isused first and the environment variable valuesecond. 

WARNING OPTIONS 

Warnings are diagnostic messages that report constructionsthat are not inherently erroneous but arerisky or suggest there 
may havebeen an errar. 

Theseoptions control theamountand kindsof warnings produced byGNU CC: 



-f syntax-only 
-w 

-Wno-import 
-pedantic 



-pedantic-errors 
-W 



C heck the code for syntax errors, but don't emit any output. 

Inhibitall warning messages. 

I nhibit warning messages about the use of #import. 

Issueall thewarningsdemanded by stri et AN SI standard C; reject ali programs that use 
forbì dden extensions. 

Valid AN SI standard C programs should compile properly with or without this option (though 
a rare few will require-ansi). H owever, without this option, certain GNU extensions and 
tradì tional C features are supported aswell. W ith this option, they are rei ected. There is no 
reason to use this option; itexistsonly to satisfy pedants. 

-pedantic does not cause warni ng messages for use of the alternate keywords whose names begi n 
and end with Pedantic warnings are al so disabled in theexpression that followsextension. 
H owever, only system header fi les should use these escape routes; application programs should 
avoid them. 

Like -pedantic, except that errors are produced ratherthan warnings. 
Print extra warning messages for these events 

A nonvolati le automati c variable might bechanged byacall to ìongjmp. These warnings are 
possi ble only in optimizing compilation. The compi ler sees only the Calisto setjmp. It cannot 
knowwhere ìongjmp will becalled; in fact, asignal handler could cali it at any point in the code. 
Asa resti It, you may get awarningeven when there is in fact no problem because ìongjmp 
cannot in fact becalled at the place which would cause a problem. 
A function can return either with or without a value. (Falli ng off the end of thefunction body 
isconsidered returning without a value.) Forexample, this function would evokesuch a 
warning: 

foo (a) 
{ 

if (a > 0) 
return a; 

} 

Spurious warnings can occur becauseGN U CC does not realize that certain functions 
(includingabort and ìongjmp) will never return. 

An expressi on-statement or the left side of a comma expression containsno side effeets. To 
suppressthewarning, casttheunused expression to void. Forexample, an expression such as 
x[i, j] will cause a warning, but x[ (void)i, j] will not. 
An unsigned value is compared against zero with > or <=. 
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-Wimplicit 
-Wreturn-type 

-Wunused 
-Wswitch 

-Wcomment 
-Wtrigraphs 
-Wf ormat 

-Wchar-subscripts 
-Wuninitialized 



Warn whenever afunction or parameter isimplicitly declared. 

Warn whenever afunction isdefined with a return-type that defaultsto int. Also warn about 
any return statement with no return -vaiue in afunction whose return-type isnot void. 
Warn whenever a locai variableisunused asidefrom itsdeclaration, whenever afunction is 
declared static but never defined, and whenever a statement computes a result that isexplicitly 
not used. 

Warn whenever a switcn statement hasan index of enumerai typeand lacksacasefor oneor 
more of the named codes of that enumeration. (T he presence of a default label prevents this 
warning.) case labels outside the enumeration rangealso provokewarningswhen thisoption is 
used. 

Warn whenever a comment-start sequence / appearsin acomment. 

W arn if any trigraphs are encountered (assumi ng they are enabled). 

Check Calisto printf and scant, and so on, to makesure that the arguments supplì ed have 

types appropriate to theformat stri ng speci fi ed. 

Warn if an array subscript hastypecnar.Thisisacommon causeof errar, as programmers 
often forget thatthistype is signed on somemachines. 
An automaticvariableisused without first bei ng i ni ti al ized. 

Thesewarnings are possi bleonly in opti mizing compilation, becausethey requiredataflow 
information that iscomputed only wnen opti mizing. If you don't specify-o, you simply won't 
get thesewarnings. 

Thesewarningsoccuronly for vari ables that are candidatesfor register allocation. Therefore, 
they do not occur for a variable that isdeclared volatile, orwhoseaddressistaken, orwhosesize 
isotherthan 1, 2, 4, or 8 bytes. Also, they do not occur for structures, unions, or arrays, even 
when they are in registers. 

N otethat theremay beno warning about a variable that isused only to computea vaiue that 
itself is never used, becausesuch computationsmay bedeleted by dataflow analysis before the 
warningsareprinted. 

Thesewarnings are made optional becauseGNU CC is not smart enough to see ali the reasons 
why the code might becorrect despiteappearing to havean errar. H ere isoneexampleof how 
thiscan happen: 
{ 

int x; 
switch (y) 
{ 

case 1 : x = 1 ; 
break; 

case 2: x = 4; 
break; 

case 3: x = 5; 
} 

foo (x); 

} 

If the vaiue of y isalwaysi, 2, or 3, then x is always i nitialized, but GN U CC doesn't know this. 
H ere isanother common case: 



int save_y; 

if (change_y) save_y 



: y,y =new_y; 



if (change_y)y 
} 



: save_y; 



Thishasno bug becausesave_y isused only if it is set. 

Somespuriouswarningscan beavoided ifyou declare asvolati le ali thefunctionsyou use that 
never return. 
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-Wparentheses 
-Wtemplate-debugging 

-Wall 



-Wtraditional 



Warn if parenthesesareomitted in certain contexts. 

When using tempi ates in a C++ program, warn if debugging isnot yet fully avai lable (C ++ 
only). 

Ali of the precedi ng -w optionscombined. Theseareall theoptionsthat pertain to usagethat 
werecommend avoidingand that we bel i ève is easy to avoid, even in conjunction with macros. 

The remai ni ng -w. . . options are not implied by -waii because they warn about constructions that we consider reasonableto 
use, on occasion, in clean programs. 

Warn about certain constructsthat behavedifferently in traditional andANSI C: 
M acro argumentsoccurringwithin stri ng constantsin themacro body. Thesewould substitute 
theargument in traditional C, but arepart of the Constant in AN SI C. 
A function declared external in one block and then used after the end of the block. 
A switch statement has an operand of type long. 
W arn whenever a locai variable shadows another locai variable. 
Warn whenever two disti net identifiers match in the first i e n characters. Thismay help you 
prepare a program thatwill compilewith certain obsolete, brain-damaged compilers. 
Warn about anything that dependson the size of a function type or of void. GNU C assigns 
thesetypesa sizeof 1, for conveniencein calculations with void pointersand pointersto 
functions. 

Warn whenever a pointer is cast so asto remove a type qualifierfrom the target type. For 
example, warn if a const char i s cast to an ordinary char. 

Warn whenever a pointer is cast such that the required alignment of the target isincreased. For 
example, warn if achar iscastto an mt on machineswhereintegers can only beaccessed at 
two- or four-byte boundaries. 

G i ve string constants the type const cnar[ length ] so that copying the address of one i nto a 
non-const char pointer wi II get awarning. Thesewarningswill help you find at compi le time 
code that can try to writei nto a string Constant, but only if you havebeen very careful about 
using const in declarationsand prototypes. Otherwise, i t wi 1 1 just bea nuisance; thisiswhy we 
did notmake-waii requestthesewarnings. 

W arn if a prototype causes a type conversion that is different from what would happen to the 
sameargumentintheabsenceofa prototype. Thisincludesco nversi o ns of f i xed po i n t to 
floating and viceversa, and conversionschangingthewidth orsignednessof afixed point 
argument exceptwhen the sameas the default promotion. 

Warn if any functions that return structuresor unionsaredefined or called. (In languages 
whereyou can return an array, thisalso elicits awarning.) 

Warn if afunction is declared or defi ned without specifying the argument types. (An old-style 
function definition ispermitted without awarning if preceded by adeclaration which specifies 
the argument types.) 

Warn if aglobal function is defi ned without a previ ous prototype deci aration. T hi swarning is 
issued even if the definition itself provi des a prototype. Theaim isto detect global functions 
thatfail to be declared in headerfiles. 

Warn if aglobal function is defi ned without a previ ous declarati on. Do so even if the definition 
itself provides a prototype. Usethisoption to detect global functionsthat are not declared in 
headerfiles. 

Warn if anything is declared morethan once in the same scope, even in caseswhere multiple 
declaration isvalid and changesnothing. 
Warn if an extern declaration isencountered within an function. 
Warn about conversion between different enumeration types (C++only). 
(C ++only.) In aderived class, the defi nitionsof virtual functions must match the type signature 
of avirtual function declared in thebase class. Usethisoption to requestwarningswhen a 
derived class declares a function that may be an erroneous atterri pt to defi ne a vi rtual function; 



-Wshadow 
-Wid-clash-l en 

-Wpointer-arith 

-Wcast-qual 
-Wcast-align 

-Wwrite-strings 



-Wconversion 

-Waggregate-return 
-Wstrict-prototypes 

-Wmissing-prototypes 

-Wmissing-declarations 

-Wredundant-decls 

-Wnested-externs 
-Wenum-clash 
-Woverloaded- virtual 
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that is, warn when there isafunction with thesamenameasa virtual function in the base class, 
but with a type signature that doesn't match any virtual functionsfrom the base class. 

-winiine Warn if a function cannot beinlined, and either itwasdeclared asini ine orelsethe-finiine- 

functions option wasgiven. 

-werror T reat warni ngs as errors; abort compilation after any warning. 

DEBUGGING OPTIONS 

GNU CC hasvarious special optionsthat are usedfor debugging either your program orgee: 

-g Produce debugging information in the operati ng system's nati ve format (stabs, COFF, XCOFF, 

or DWARF). GD B (theGN U debugger) can work with thisdebugging information. 
0 n most systems that use stabs format, -g enables use of extra debugging i nformati on that only G D B 
can use; this extra information makes debugging work better in G D B but will probably make 
other debuggers crash or refuse to read the program. If you want to control for certain whether 

tO generate the extra information, USe-gstabs, -gstabs, -gxcoff+, -gxeoff, -gdwarf+, Or-gdwarf. 

Unlike most other C compilers, GNU CC allows you to use -g with -o. Theshortcutstaken by 
optimized codemay occasionally produce surpri si ng results: Some variables you declared may 
notexist atall; flow of control may briefly move where you did notexpect it; somestatements 
may not be executed because they compute Constant results or their values were al ready at hand; 
somestatements may execute in different places becausethey were moved outof loops. 
N evertheless, it proves possi bleto debug optimized output. This makes it reasonableto use the 
optimizer for programs that might have bugs. 

Thefollowing opti ons are useful when GN U CC isgenerated with thecapability for morethan one debugging format. 

-ggdb Produce debugging i nformation in the native format (if that is supported), includi ng G D B 

extensionsi fatali possible. 

-gstabs Produce debugging information in stabs format (if that issupported), without GD B exten- 

sions. This is the format used by D BX on most BSD systems. 
-gstabs+ Produce debugging i nformation in stabsformat (if that issupported), usingGNU extensions 

understood only by theGN U debugger (GD B). The use of these extensions is likely to make 

other debuggers crash or refuse to read the program, 
-geoft Produce debugging information in COFF format (if that issupported). Thisis the format used 

by SD B on most System V systems prior to System V Release4. 
-gxeoff Produce debugging information in XCOFF format (if that issupported). Thisis the format 

used bytheDBX debugger on IBM RS/6000 systems. 
-gxeoff + Produce debugging information in XCOFF format (if that issupported), using GN U 

extensions understood only by the G N U debugger (G D B). T he use of these extensions is li kely 

to make other debuggers crash or refuse to read the program, 
-gdwarf Produce debugging i nformation in DWARF format (if that is supported). This is the format 

used by SD B on most System V Release 4 systems. 
-gdwarf+ Produce debugging information in DWARF format (if that issupported), usingGNU 

extensions understood only by the G N U debugger (G D B). T he use of these extensions is li kely 

to make other debuggers crash or refuse to read the program. 

-glevel 
-ggdbl evel 
-gstabsl evel 

-gcofflevel -gxcofflevel 

-gdwarfi evel Request debugging information and also usei evel to specify how much information. The 

default level is 2. 

Level 1 produces minimal information, enough for making backtracesin parts of the program 
that you don't pian to debug. T his includes descri ptionsof functions and external variables, but 
no information about locai variables and no linenumbers. 
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Level 3 i ncludes extra informati on, such asall themacro definitions present in theprogram. 

Somedebuggerssupport macro expansion when you use-g3. 
-p G en erate extra codeto wri te profile information sui tablefor the analysis program prof, 

-pg Generate extra codeto write profile information suitablefor the analysis program gprof . 

-a G en erate extra codeto write profile information for basic blocks, which will record thenumber 

oftimeseach basic block isexecuted. Thisdata could beanalyzed by aprogram liketcov. Note, 

however, that the format of the data isnot what tcov expects. Eventually, GNU gprof should 

beextended to process thisdata. 
-di etters Saysto make debugging dumps during compi lation attimesspecified byi etters. Thisisused 

for debugging the compi ler. Thefilenamesfor most of the dumps are madeby appendi ng a 

word to the source filmarne (for example, foo.c.rti orfoo.c.jump). 
-dM Dump ali macro defini ti onsat the end of preprocessing, and write no output. 

-dN Dump ali macro names, at the end of preprocessing. 

-dD Dump ali macro defini ti onsat the end of preprocessing, in addition to normal output, 

-dy Dump debugging information during parsing, to standard errar, 

-dr Dump after RTL generation, to file. rti. 

-dx Just generate RTL for afunction instead of compi li ng it. Usually used with r. 

-dj Dump after first jump optimization, to f i i e jump. 

-ds Dump after C SE (includi ng the jump optimization that sometimesfollowsCSE), to file . cse. 

-di_ Dump after loop optimization, to fi i e loop. 

-dt Dump after the second CSE pass (includi ng the jump optimization thatsometimesfollows 

CSE), tO f i I e . cse2. 

-df Dump after flow analysis, to fi i e fiow. 

-de Dump after instruction combination, tof i i e .combine. 

-ds Dump after thefirst instruction scheduli ng pass, to f i i e . scned. 

-di Dump after locai resisterai location, to f i i e ireg. 

-dg D ump after global register allocation, to file . greg. 

-dR Dump after thesecond instruction scheduling pass, to fi i e .scned2. 

-dJ Dump after lastjump optimization, tof i i e .jump2. 

-dd Dump after delayed branch scheduling, tof i i e .dbr. 

-dk Dump after conversion from registersto stack, tof i i e .stack. 

-da Produce ali the dumps listed previously. 

-dm P ri nt stati sticson memory usage, at the end of therun, to standard errar, 

-dp Annotate the assembler output with a comment indicati ng which pattern and alternative was 

used. 

-fpretend-fioat When running a cross-compiler, pretend that the target machineusesthesamefloating-point 

format as the host machi ne. T his causes i ncorrect output of the actual f loati ng constante, but 

theactual instruction sequencewill probably bethesameasGN U CC would make when 

running on thetarget machine, 
-save-temps Storetheusual temporary intermediatefiles permanently; placethem in thecurrent directory 

and namethem based on thesourcefile Thus, compilingfoo.c with -c -save-temps would 

produce fi lesf oo. epp and foo.s, aswell asfoo.o. 
-print-fiie-name=i i brary Print the full absolute name of the library file i brary would beused when linking, and do not 

do anythingelse. With thisoption, GN U CC doesnot compi le or link anything; itjust prints 

thefilename. 

-print-libgcc-f ile-name Same as-print-file-name=libgcc.a. 



-print-prog-name=program Like -print-f ile-name, but Searches for a program SUCh aScpp. 
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OPTIMIZATION OPTIONS 

These options control various sorts of optimizations: 

-o, -01 Optimize Optimizing compilation takessomewhat more ti me, and a lot morememory for a 

largefunction. 

Without -o, the compilerà goal isto reduce the costof compilation and to make debugging 
produce the expected results. Statementsareindependent: If you stop the program with a 
breakpointbetween statements, you can then assign a new valueto any variableorchangethe 
program counter to any other statement in thefunction and get exactly the results you would 
expect from the source code. 

Without -o, only variablesdeclared regi ster are al I ocated in registers. T he resulting compi led 

code is a little worsethan produced by PCC without -o. 

With -o, the compi ler tri esto reduce code si ze and execution time. 

When you specify-o, thetwo options -fttiread-jumps and -fdefer-pop areturned on. On 
machinesthat havedelay slots, the-fdeiayed-branch option isturned on. Forthosemachines 
thatcan support debugging even without a f rame pointer, the -fomit-f rame-pointer option is 
turned on. On somemachinesotherflagsmay also beturned on. 
-02 Optimizeeven more. Nearlyall supported optimizationsthatdo not involvea space-speed 

tradeoff are performed. Loop unrolling and function inlining are not done, for example As 
compared to -o, this option increasesboth compilation ti me and the performance of the 
generated code 

-03 Optimizeyet more. This turnson everything-02 does, along with also turni ng on -tiniine- 

f unctions. 

-00 Do not optimize 

If you use multi pie -0 options, with or without leve! numbers, thelast such option istheone 
that is effective 

Options of theform -t f i a g specify machine-i ndependent flags. M ost flagshaveboth positive and negativeforms; the 
negative form of -ttoo would be-tno-too. Thefollowing list showsonly oneform— theonewhich isnot the default. You 
can figure out the other form by either removi ng no- or adding it. 

-ftioat-store Do not store f loati ng-poi nt vari ables i n registers. This prevents undesi rable excess precision on 

machi nes such as the 68000 where the floati ng regi sters (of the 68881) keep more precision 
than a doublé is supposed to have. 

Formost programs, the excess precision does only good, but a few programsrely on the precise 
definition of IEEE floati ng point. Use-ttioat-store for such programs. 
-fmemorize-iookups U se heuristicsto compi I e faster (C-H-only). These heuristics are not enabled by default, 

-tsave-memorized si nce they are only effectivefor certain input fi les. Other input fi les compi le more slowly. 

The first ti me the compi ler must bui Id a cali to a member function (or referenceto a data 
member), it must (1) determi ne whether the class implements member functionsof that name; 
(2) resolvewhich member function to cali (which involvesfiguring out what sorts oftype 
conversi onsneed to bemade); and (3) check the visibility of the member function to the Caller. 
Ali of thisaddsup to slower compilation. N ormai ly, thesecond ti me a cali ismadeto that 
member function (or referenceto that data member), it must go through thesamelengthy 
process agai n. This means that code like this: 

cout « "This " « p « "has"« \ « " legs.\n" 

makessix passes through ali threesteps. By usi ng a software cache, a hit significantly reduces 
thiscost. U nfortunately, usi ng the cache introduces another layer of mediani sms which must 
beimplemented, and so incursitsown overhead. -fmemorize- ìookups en ables the software 
cache. 

Because access privileges (visibility) to membersand member functionsmay differ from one 
function context to thenext, g++ may need to flush the cache. W ith the -fmemorize-iookups 
flag, the cache is flushed after every function that iscompiled. The -tsave-memorized flag 
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FI 



-f no-def ault -inline 
-f no-defer-pop 

-f f orce-mem 

-fforce-addr 
-fomit-f rame-pointer 



enables the same software cache, but when the compi ler determi nes that the context of the last 
function compiled would yield the same access privi legesof thenextfunction to compile, it 
preserves the cache. Thisismost helpful when defining many memberfunctionsfor the same 
class: with theexception of memberfunctionswhich arefriendsof other classes, each member 
function hasexactly the same access privi leges as every other, and the cache need not beflushed. 
D on't make member functions inli ne by default merely because they are defi ned inside the class 
scope (C-H-only). 

Alwayspop theargumentsto each function cali assoon as that function returns. For machines 
which must pop arguments after a function cali, the compi ler normally lets arguments 
accumulate on thestackforseveral function callsand popsthem ali atonce. 
Force memory operandsto becopied into registers before doing arithmetic on them. Thismay 
produce better code by making ali memory references potential common subexpressions. W hen 
they are not common subexpressions, instruction combination should eli mi nate the separate 
register-load. I am interested in hearing aboutthedifferencethismakes. 
Force memory addressconstantsto becopied into registers before doing arithmetic on them. 
Thismay produce better codejustas-fforce-mem may. I am interested in hearing about the 
differencethismakes. 

Don't keep the frame pointer in a regi ster for functions that don't need one. T hisavoids the 
instructionsto save, set up and restare frame poi nters; it also makesan extra regi ster availablein 
many functions. It also makes debugging impossibleon most machines. 
On some machines, such astheVAX, thisflag hasno effect because the standard calling 
sequenceautomatically handles the frame pointer and nothing issaved by pretendi ng it doesn't 
exist. Themachine-description macro frame_pointer_required controlswhether a target 
machi ne supports thisflag. 

Integrate ali si mple functions into their cai lers. The compi ler heuristi cally deci des which 
functions are simpleenough to beworth integrati ng in thisway. 
If ali Calisto a given function areintegrated, and the function isdeclared static, then gcc 
normally doesnot output the function as assembler code in itsown right. 
Enablevaluesto beallocated in registers that wi II beclobbered by function cai I s, by emitting 
extra instructionsto save and restare the registers around such cai I s. Such allocation isdone 
only when it seemsto result in better codethan would otherwise beproduced. 
Thisoption isenabled by default on certain machines, usuallythose which havenocall- 
preserved regi sters to useinstead. 

Even if ali Calisto agiven function areintegrated, and thefunction isdeclared static, 
nevertheless output a separate runti me callable versi on of thefunction. 
Do not put function addressesin registers; make each instruction that calls a Constant function 
contai n thefunction'saddressexplicitly. 

Thisoption resultsin less efficient code, but some strangehacks that alter the assembler output 
may beconfused by theoptimizationsperformed when thisoption isnot used. 
D isableany machi ne-specific peepholeoptimizations. 

Thisoption allowsgcc to violate some AN SI or IEEE specificationsin the interest of optimiz- 
ing codefor speed. For example, it allows thecompiler to assume arguments to the sqrt 
function are nonnegative numbers. 

Thisoption should never beturned on by any-o option because it can result in incorrect 
output for programs which depend on an exact im pi ementati on of IEEE or AN SI rules/ 
speci fi cations for math functions. 

T he followingoptions control specific opti mizations. The -02 option turnson ali of theseoptimizationsexcept -funroii- 

loops and -funroll-all-loops. 



-f inline-f unctions 
-fcaller-saves 

-fkeep-inline-f unctions 
-f no-f unction-cse 



-f no-peephole 
-ffast-math 



The-o option usually turnson the-fthread-jumps and -fdeiayed-brancn options, but specific machines may changethe 
default opti mizations. 
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-f strength-reduce 
-fthread-jumps 



-f unroll-loops 
-f unroll-all-loops 
-fcse-follow-jumps 

-fcse-skìp-blocks 

-f rerun-cse-after-loop 
-felide-constructors 



You can use the following flags in the rare caseswhen fine-tuning of optimizationsto beperformed isdesired: 

Perform theoptimizationsof loop strength reduction and elimination of iteration variables. 
Perform opti mizationswherewe check to seeif ajump branchesto a location whereanother 
compari son subsumed bythefirst isfound. If so, thefirst branch isredirected to eitherthe 
desti nati on of thesecond branch or a poi nt immedi ately following it, dependi ngon whether 
thecondition isknown to betrueorfalse. 

Perform the opti mization of loop unrolling. Thisisonly donefor loopswhosenumberof 
iterationscan bedetermined at compiletimeor runtime. 

Perform the opti mization of loop unrolling. Thisis donefor ali loops. Thisusually makes 
programsrun moreslowly. 

In common subexpression elimination, scan through jump instructionswhen the target of the 
jump isnot reached by any other path. For example, when CSE encountersan if statement 
with an else clause, CSE will follow thejump when thecondition tested is false. 
This issimilar to -fcse-foiiow-jumps, but causesCSE to follow jumpswhi eh condì tionally skip 
over blocks. When CSE encountersasimpleif statement with no else clause, -fese-skip- 
biocks causes C SE to follow thejump around the body of the if . 
Rerun common subexpression elimination after loop optimizationshas been performed. 
Elideconstructorswhen thisseems plausi ble (C++ only). With thisflag, GNU C++initializesy 
directly from the cali to foo without going through atemporary in the following code 
Afoo();Ay=foo(); 

Without this opti on, GNU C++ first initializesy by cai li ng the appropriate constructor for type 
A; then assi gns the result of foo to atemporary; and, finally, replacestheinitial valueof y with 
the tempo rary. 

The default behavior(-fno-eiide-constructors) isspecified by thedraft AN SI C++standard. If 
your program 'sconstructorshave si de effeets, using -f elide -constructors can makeyour 
program act differently, since some constructor callsmay beomitted. 
Perform a number of minor optimizations that are relatively expensive. 
If supported for the target machine, attempt to reorder instructionsto exploit instruction slots 
available after delayed branch instructions. 

If supported for the target machine, attempt to reorder instructionsto eliminateexecution stalls 
dueto required data being unavailable This helps machinesthat haveslow floating point or 
memory load instructions by allowing other instructionsto beissued until the result of theload 
or floating point instruction is required. 

Similarto -fscheduie-insns, but requestsan additi onal passof instruction scheduli ng after 
regi ster al location hasbeen done. This is especially useful on machineswith a relatively sm ali 
number of registers and where memory load instructionstakemorethan onecycle. 

TARGETOPTIONS 

By default, GN U CC compiles code for the same type of machine that you are using. 

H owever, it can also beinstalled asacross-compiler, to compi le for some other type of machine. In fact, several different 
confi gurations of GN U CC, for different target machines, can beinstalled side by side. Then you specify which oneto use 
with the-b option. 

In addition, olderand newer versi onsof GNU CC can beinstalled side by side. Oneof them (probably the newest) will be 
the default, but you may sometimeswantto useanother. 

-b machine T he argument ma c h i ne specifies the target machinefor compi lation. This is useful when you 

have installed GNU CC asacross-compiler. 

Thevalueto usefor ma c hi ne is the same aswasspecified as the machine type when confi guring 
GNU CC asacross-compiler. For example, if a cross-compilerwasconfigured with configure 



-fexpensive-optimizations 
-f delayed-branch 

-f schedule-insns 



-f schedule-insns2 
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i386v, meaningto compi le foran 80386 run ni ng System V, then you would specify -b i386v to 
run that cross compila - . 

When you do not specify -b, it normally meansto compi le for the sametypeof machine that 
you are usi ng. 

-v versi on T he argument ver s i o n specifieswhich versi on of GN U CC to run. Thisisuseful when multiple 

versi ons are instai led. Forexample, versi on mightbe2.o, meaningto run GNU CC version 
2.0. 

The default version, when you do not specify -v, is controlied bytheway GNU CC isinstalled. 
Normally, itwill bea version that isrecommended for general use. 

MACHINE-DEPENDENT 0PTI0NS 

Each ofthetarget machine typescan haveitsown special options, starti ngwith -m, to chooseamong various hardware 
modelsor configurations— for example, 68010 versus 68020, floatingcoprocessor or none A single installed version of the 
compiler can compilefor any model or configuration, according to theoptionsspecified. 

Some configurati ons of the compi ler also support additional special options, usuai ly for command-li ne compati bili ty with 
other compi lerson thesameplatform. 

Thesearethe-m options defi ned for the 68000 seri es: 



-m68000 
-mc68000 

-m68020 
-mc68020 

-m68881 
-m68030 
-m68040 
-m68020-40 
-mf pa 

-msoft-float 



Generate output fora68000. Thisisthe default when thecompiler isconfigured for 68000- 
based system s. 

G enerate output for a 68020 (rather than a 68000). Thisisthe default when thecompiler is 
confi gured for68020-based systems. 

G enerate output contai ning 68881 instructionsfor floating point. This is the default for most 
68020-based systems un less -nfp wasspecified when the compiler was confi gured. 
Generate output for a 68030. Thisisthe default when thecompiler isconfigured for 68030- 
based systems. 

Generate output for a 68040. Thisisthe default when thecompiler isconfigured for 68040- 
based systems. 

Generate output for a 68040, withoutusingany of thenew instructions. Thisresults in code 
which can run rdatively efficiently on either a 68020/68881 or a 68030 or a 68040. 
G enerate output containing Sun FPA instructionsfor floating point. 
G enerate output containing library calls for floati ng point. 



WARNING 



The requisite li braries are not part of GN U CC. N ormally, the faci li tiesof the machine's usuai C compiler are used, but 
thiscan't bedonedirectly in cross-compilation. You must makeyour own arrangementsto provide suitable library func- 
tionsfor cross-compilation. 



-msbort Considertype int to bel6 bits wide, li ke short int. 

-mnobitfìeid Do not use the bit-fi eld instructions. -m68000 implies-mnobitfieid. 

-mbitfieid D o use the bit-field instructions. -m68020 implies -mbitf ieid. Thisisthe default if you usethe 

unmodified sources. 

-mrtd U se a different function-calling convention, in which functionsthat takea fixed number of 

arguments return with thertd instruction, which popstheir argumentswhi le returni ng. This 
savesoneinstruction in the Caller si ncethereis no need to pop the arguments there. 
This cali ing convention isincompatiblewith the one normally used on U N IX, so you cannot 
useit if you need to cali li braries compi led with theU N IX compiler. 
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Also, you must provide function prototypes forali functions thattakevariablenumbersof 
arguments(including printf ); otherwise, incorrect code wi II begenerated for Calisto those 
functions. 

In additi on, seriously incorrect code wi II result if you cali a function with too many arguments. 
(N ormally, extra arguments are harmlessly ignored.) 

Thertd instruction issupported by the 68010 and 68020 processors, but not by the 68000. 
These-m optionsare defined for the VAX: 

-munix Do not output certai n jump instructions(aobieq and so on) thattheU N IX assembler for the 

VAX cannot handleacross long ranges. 
-mgnu D o output thosejump instructions, on theassumption thatyou wi 1 1 assemblewith theGN U 

assembler. 

-mg Output codeforg-formatfloating-point numbers instead of d-format. 

These-m switchesaresupported on thesPARc: 

-mfpu Generate output contai ning floati ng-point instructions. This isthe default. 

-mhard-f loat 

-mno-fpu G enerate output containing library calls for floati ng point. 

-msoft-float 



WARNING 



ThereisnoGNU floati ng-point library for SPARC. N ormally, the faci I iti esof the machine's usuai C compilerareused, 
but this cannot bedonedirectly in cross-compilation. You mustmakeyourown arrangementsto providesuitablelibrary 
functions for cross- compilation. 



-msoft-float 

-mno-epilogue 
-mepilogue 



-mno-v8 
-mv8 

msparclite 



Changes the calli ng convention in the output file; therefore it isonly useful if you compi le ali 
of a program with thisoption. 

With -mepilogue (the default), the compiler alwaysemits code forfunction exitattheend of 
each function. Any function exit in the middle of the function (such as a return statement in C) 
will generate a jumpto the exit code at the end of the function. W ith -mno-epiiogue, the 
compiler tri esto emit exit codeinlineat every function exit. 

Thesethreeoptionsselect variationson the SPARC architecture. By default (unless specificai ly 
confi gured for the Fujitsu SPARC lite), geo generates code for the v7 variant of the SPARC 
architecture. 

-mv8 will giveyou SPARC v8 code. The only differencefrom v7 code isthat the compiler emits 
the integer multiply and integer divide instructions thatexist in SPARC v8 but not in SPARC v7. 
-msparclite will giveyou SPARC lite code. T his adds the integer multiply, integer divide step 
and scan (ffs) instructionsthat exist in SPARC lite but not in SPARC v7. 
T hese two options select the processor for which the code is optimized. 
With -mcypress (the default), the compiler optimizescodefortheCypressCY7C602 chip, as 
used in theSparcStation and SparcServer 3xxseries. This is also appropriate for the older 
SparcStation 1, 2, IPX, and so on. 

With -msupersparc the compiler opti mizes code for the SuperSparccpu, asused in the 
SparcStation 10, 1000, and 2000 seri es. Thisf lag also enables use of the full SPARC v8 
instruction set. 

These-m optionsare defined fortheConvex: 

-mei G enerate output for a CI. This isthe default when the compiler isconfigured for a CI. 

-mc2 G enerate output fora C 2. This isthe default when the compiler isconfigured for a C 2. 



-mcypress 
-msupersparc 
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-margcount 



-mnoargcount 



Generate code whi eh putsan argument count in the word precedi ng each argument list. Some 
nonportableConvexand VAX programsneed thisword. (Debuggersdon't, exceptfor 
functions with variable-length argument lists; thisinformation is i n the symbol table.) 
Omit the argument count word. This is the default if you usetheunmodified sources. 

These-m optionsaredefined fortheAM D Am29000: 

-mdw Generate code that assumestheDW bit is set, that is, that byte and half-word operationsare 

directly supported by the hardware. This is the default, 
-mnodw G enerate code that assumes the D W bit is not set. 

-mbw Generate code that assumes the system supports byte and halfword write operations. This isthe 

default. 

-mnbw G enerate code that assumes the systems does not support byte and halfword write operati ons. 

This implies -mnodw. 

-msmaii Useasmall memory model that assumes that ali function addresses are either within asingle 

256KB segment or at an absoluteaddressof lessthan 256K. Thisallowsthecaii instruction to 
beused instead of aconst, consth, cain sequence 

-miarge D o not assume that the cali instruction can beused; this isthedefault. 

-m29O50 G enerate code for the A m29050. 

-m2900B Generate code for the A m29000. This isthe default. 

-mkernei-registers G enerate references to registersgr64-gr95 instead of gr96-gn27. T hisoption can beused when 

compi ling kernel codethatwantsaset of global registers disjoint from that used by user-mode 
code. 

N ote that when this opti on isused, register namesin -f flagsmust usethenormal, user-mode, 
names. 

-muser-registers Usethenormal set of global registers, gr96-gn27. Thisisthe default. 

-mstack-check Inserta cali to msp check after each stack adjustment. Thisisoften used for kernel code. 



These-m optionsaredefined for M otorola 88K architectures: 

-m88000 
-m88100 
-m88110 

-midentif y-revision 



-mno-underscores 



-mcheck-zero-division 
-mno-check-zero-division 



-mocs-debug-info 
-mno-oes-debug-info 



-mocs-f rame-position 
-mno-oes-f rame-position 

-moptimize-arg-area 
-mno-optimize-arg-area 



Generate code that works well on both them88100 and them88110. 
G enerate code that works best for the m88100, but that also runs on the m88110. 
G enerate code that works best for the m88110, and may not run on them88100. 
Include an ident di recti ve in the assembler output recordi ng the source fi lename, compi ler 
nameand version, timestamp, and compilation flagsused. 

In assembler output, emit symbol nameswithoutaddingan underscorecharacteratthe 
beginning of each name. The default isto usean underscoreasprefix on each name. 
Early modelsof the88K architecturehad problemswith division byzero; in particular, manyof 
them didn'ttrap. Usetheseoptionsto avoid including (or to include explicitly) additional code 
to detect division byzero and signal an exception. Ali gcc configurationsfor the 88K use 

-mcheck-zero-division by default. 

Include (or omit) additional debugging informati on (about registers used in each stack frame) 
asspecified inthe880pen 0 bject C ompatibility Standard, OCS. This extra information isnot 
needed by G DB. The default for DG/UX, SVr4, and Delta 88 SVr3.2 isto include this 
information; other88K configurationsomitthisinformation by default. 
Force (or do not require) register valuesto bestored in a particular place in stack frames, as 
specified in OCS. The DG/UX, D elta88 SVr3.2, and BCS configurations use -mocs-f rame- 
position; other 88K configurations h ave the default -mno-ocs- f rame-position. 
Control how to store function arguments in stack frames, -moptimize-arg-area saves space, but 
may break some debuggers (not G D B). -mno-optimize-arg-area conforms better to standards. 
By default gcc does not opti mize the argument area. 
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-mshort-data-nijm 



-mserialize- volatile 
-mno-serialize- volatile 



-msvr4, -msvr3 



-mtrap-large-shift 

-mhandle-large-shift 

-muse-div-instruction 

-mversion-03. 00 



-mwarn-passed-structs 



Generate smaller data referencesby making them relative to re, which allows loading a value 
usi ng a single instruction (rather than the usuai two). You control which data references are 
affected by specifying num with thisoption. Forexample, if you specify-mshort-data-512, 
then the data references affected arethoseinvolving displacementsof lessthan 512 bytes. 
-mshort-data-num is not effective for n u m greater than 64K. 

Do, or do not, generate code to guaranteesequential consistencyof volatile memory references. 
GNU CC alwaysguaranteesconsistency by default, for the preferred processor submodel. How 
this is done depends on the submodel. 

Them88100 processor doesnot reorder memory references and so always provi dessequenti al 
consistency. If you use -11188100, GNU CC does not generate any special instructionsfor 
sequential consistency. 

Theorder of memory references madeby them88110 processor does not always match the 
orderof the instructions requesti ngthose references. In parti cular, aload instruction may 
executebeforeaprecedingstoreinstruction. Such reordering violates sequential consistencyof 
volatile memory references, when there are multiple processors. When you use-m88000 or 
-m88ii0, GN U CC generates special instructionswhen appropriate, to force execution in the 
proper order. 

The extra codegenerated to guarantee consistency may affect the performance of your 
application. If you know thatyou can safelyforgo this guarantee you may use the opti on 

-mno-serialize -volatile. 

Ifyou usethe-m88i00 option but requi re sequential consistency when runningon them88110 

processor, yOU Should use -mserialize -volatile. 

Turn on (-msvr4) or off (-msvr3) compilerextensionsrelated to System V release4 (SVr4). This 
controis thefollowing: 

Which variant of the assembler syntaxto emit (which you can select independently using 

-mversion-03. 00). 

-msvr4 makestheC preprocessor recognize#pragma weak. 

-msvr4 makesgee issue additional declaration d i recti vesused in SVr4. 

-msvr3 isthe default for ali m88K configurationsexcepttheSVr4configuration. 

Include code to detect bit-shiftsof more than 31 bits; respectively, trap such shiftsor emit code 

to handlethem properly. By default, geo makes no special provision for large bit shifts. 

Very early modelsof the 88K archi tecture didn't have a divide instruction, so gec avoids that 

instruction by default. Use thisoption to specify that it'ssafeto use the divide instruction. 

In theDG/U X confi guration, there are two flavorsof SVr4. Thisoption modifies-msvr4 to 

select whether the hybrid-C 0 FF or real-ELF flavor is used. AH other confi gurations ignore this 

option. 

Warn when afunction passesastruct asan argument or restii t. Structure- passi ng conventions 
havechanged during the evoluti on of theC language, and areoften thesourceof portabi I ity 
problems. By default, gec issuesno such warning. 



Theseoptionsaredefined forthelBM RS6000: 

-mfp-in-toc Control whether or notfloating-point constantsgo in thetableof contents(TOC), a tableof 



-mno-f p-in-toc 



ali global variableand function addresses. By default gec putsfloating-point constants there if 
theTOC overflows, -mno-fp-in-toc will reduce the sizeof theTOC, which mayavoidthe 
overflow. 



These-m optionsare defined forthelBM RT PC: 

-min-iine-mui Usean i ni ine code sequence for integer multiplies. This isthe default, 

-mcaii-iib-mui Cali imuis$ for integer multiples. 

-mfuii-fp-biocks Generate full-size floati ng-poi nt data blocks, includi ng the minimum amount of scratch space 

recommended by IBM .This is the default. 
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-mminimum-f p-blocks 
-mfp-arg-in-f pregs 



-mf p-arg-in-gregs 
-mhc-struct-return 



-mnohc-struct-return 



Do not include extra scratch space i n fi oating- poi nt data blocks. T his results in smaller code, 

but slower execution, since scratch space must beallocated dynamically. 

U se a calling sequence incompatible with thelBM calling convention in which floating-point 

argumentsarepassed in floating-point registers. N otethat varargs.h and stdargs.n will not 

work with floati ng-poi nt operands if this option is specified. 

Usethenormal calling convention for floating-point arguments. This is the default. 

Return structuresof morethan oneword in memory, rather than in a register. This provides 

compati bility with theM etaWareH ighC (he) compiler. Use-fpcc-struct-return forcompat- 

ibility with thePortableC Compiler (PCC). 

Return some structuresof morethan oneword in registers, when convenient. Thisisthe 
default. For compatibility with the IBM -supplied compilers, useeither-fpcc-struct-return or 

-mhc-struct-return. 



These-m optionsare defined for theM IPSfamily of computers: 



-mcpu=c p u- 1 y p e 



-mips2 
-mips3 

-mint64, -mlong64 

-mlonglong128 

-mmips-as 



-mgas 



-mrnames, -mno-rnames 



-mgpopt, -mno-gpopt 



-mstats, -mno-stats 



-mmemcpy, -mno-memcpy 

-mmips-tf ile 
-mno-mips-tf ile 



-msoft-float 



Assume the defaults for the machine typeepu-type when scheduli ng instructions. The default 
epu-type is default, which picks the longest cycles times for any of themachines, in orderthat 
thecoderun at reasonablerateson ali M IPSCPUs. Other choicesfor c pu- 1 ype arer2000, «000, 
r4000,and r6000. W hile picking a specific c pu - 1 y pe will schedule things appropri ately for that 
parti cular chip, the compiler wi II not generate any code that does not meet level 1 of the M I PS 
ISA (instruction set architecture) with-out the-mips2 or-mips3 switchesbeingused. 
Issue instructions from level 2 of theM I PS ISA (branch likely, squareroot instructions). 
The-mcpu=r4000 or -mcpu=r6000 switch must beused in conjunction with -mips2. 
Issue instructions from level 3 of theM I PS ISA (64-bit instructions). The-mcpu=r4000 switch 
must beused in conjunction with -mips2. 
Theseoptionsdon'twork at present. 

Generate code for theM IPS assembler, and invokemips-tfiie to add normal debug informa- 
tion. Thisisthe default for ali platformsexceptfortheOSF/1 reference platform, using the 
OSF/roseobject format. If any of the-ggdb, -gstabs, or-gstabs+ switchesareused, themips- 
tfiie program will encapsulatethestabswithin M IPS ECOFF. 
Generate code for theGNU assembler. Thisisthe default on theOSF/1 reference platform, 
usi ng the 0 SF/rose object format. 

The -mrnames switch saysto output code using the M IPS software names for the registers, 
instead of the hardware names (for exam pie, a0 instead of $4). TheGN U assembler does not 
support the -mrnames switch, and theM IPS assembler will beinstructed to run theM IPS C 
preprocessor over the source fi le. The -mno-rnames switch is default. 
The -mgpopt switch saysto writeall of the data declarations before the instructions in thetext 
section, to ali theM IPS assembler to generate one-word memory references i nstead of using 
two wordsfor short global or stati c data items. Thisison by default if optimization isselected. 
Foreach noninlinefunction processed, the-mstats switch causes the compi lerto emit one line 
to thestandard errar fi le to print stati sticsabout the program (numberof registers saved, stack 
size, and so on). 

The-mmemcpy switch makesall block movescall the appropriate string function (memepy or 
bcopy) instead of possibly generating inlinecode. 

The -mno-mips-tf ile switch causes the compiler to not post-process the object file with the 
mips-ttiie program, after theM IPS assembler hasgenerated it to add debug support. If mips- 
ttiie isnot run, then no locai variables will beavailableto thedebugger. In addition, stage2 
and stage3 objects wi II havethetemporary filenamespassed to the assembler embedded in the 
object file which means the objects will not co m pare th esame. 
G enerate output containing library callsforfloating point. 
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WARNING 



The requisite li braries are not part of GN U CC. N ormally, the faci li tiesof the machine's usuai C compi ler are used, but 
thiscan't bedonedirectly in cross-compilation. You must makeyour own arrangementsto provide suitable library func- 
tionsfor cross-compilation. 



-mhard-f loat 



-mfp64 



-mfp32 

-mabicalls 

-mno-abicalls 

-mhalf-pic 

-mno-half-pic 

-Gnum 



-nocpp 



G enerate output containingfloating point instructions. Thisisthe default if you use the 
unmodified sources. 

Assume that the fr bit in the status word ison, and that there are 32 64-bit fi oati ng-point 
regi sters, instead of 32 32-bit floati ng-point regi sters. You must also speci fy the -mcpu=r4000 and 
-mips3 switches. 

Assume that there are 32 32-bit floati ng-point regi sters. Thisis the default. 

Emit (or do not emit) the .abicaiis, .cpioad, and .cprestore pseudo operations that some 

System V.4 portsusefor position-independent code. 

The -mhaif-pic switch saysto put pointersto extern references into the data section and load 
them up, rather than put the references in thetext section. This option does not work at 
present. 

Put global and stati c itemslessthan or equal to num bytesinto thesmall data or bss sections 
instead of thenormal data or bss section. This al lows the assembler to emit one-word memory 
reference instructions based on the global pointer (gp or $28), instead of thenormal two words 
used. By default, num iss when the M I PS assembler isused, and 0 when theGN U assembler is 
used. The -Gnum switch isalso passed to theassembler and linker. Ali modulesshould be 
compi led with thesame-Gnum value. 

Teli theM IPS assembler to not run its preprocessor over user assembler fi les (with an .s suffix) 
when assemblingthem. 



These-m optionsare defined for the Intel 80386 family of computerà 

-m486, -mno-486 Control whether or not code is opti mized for a 486 instead of a 386. Codegenerated for a 486 

will run on a 386 and viceversa, 
-msoft-fioat G enerate output containing library calls for floati ng point. 



WARNING 



The requisite li braries are not part of GN U CC. N ormally, the faci li tiesof the machine's usuai C compi ler are used, but 
thiscan't bedonedirectly in cross-compilation. You must makeyour own arrangementsto provide suitable library func- 
tionsfor cross-compilation. 



On machineswhereafunction returns floati ng point resultsin the 80387 register stack, some 
floating-pointopcodesmay beemitted even if -msoft-fioat isused. 
-mno-fp -ret-in-387 D o not use the FPU regi stersfor return valuesof functions. 

Theusual cai I i ng convention has functions return valuesof typesfloat and doublein an FPU 
register, even if there is no FPU . The idea isthat the operati ng system should emulate an FPU . 
Theoption -mno-fp-ret-in-387 causessuch valuesto bereturned in ordinary CPU registers 
instead. 

These-m optionsare defined for the H PPA family of computerà 
-mpa-risc-1 -a G enerate code for a PA 1.0 processor. 

-mpa-risc-1 -1 G enerate code for a PA 1.1 processor. 
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-mkernei G enerate code which is suitable for use in kernels. Specifi cally, avoid acid instructions in which 

oneof theargumentsistheD P regi ster; generate addii instructions instead. Thisavoids a rather 

serious bug in theH P-UX linker. 
-mshared-iibs G enerate code that can belinked against H P-UX shared libraries. Thisoption isnotfully 

functioningyet, and isnot on by default for any PA target. U si ng thisoption can cause 

incorrect codeto begenerated by thecompiler. 
-inno- shared -ìibs D on't generate code that wi II belinked against shared libraries. This is the default for ali PA 

targets. 

-miong-caiis G enerate code which allows Calisto functionsgreaterthan 256K away from thecallerwhen the 

Caller and callee are i n thesamesourcefile. Do notturn thisoption on unlesscoderefusesto 
link with branch out of range erro rs from the linker. 

-mdisabie-fpregs Prevent floati ng-poi nt regi sters from beingused in any manner. This isnecessary for compi li ng 

kernels that perform lazy context switching of floati ng-poi nt registers. If you use thisoption 
and atterri ptto perform floating-point operations, the compi ler wi II abort. 

-mdisabie-indexing Prevent the compiler from usi ng indexing address modes. This avoids some rather obscure 

problemswhen compi ling M IG-generated code under MACH . 

-mtraiiing- colon Add a colon to the end of label defi niti ons (for ELF assemblers). 

These-m options are defi ned for the Intel 80960 familyof computerà 



-me p u ■ t y p e 

-mnumerics 
-msoft-float 
-mleaf-procedures 
-mno-leaf-procedures 



-mtail-call 
-mno-tail-call 



-meomplex-addr 
-mno-complex-addr 



-mcode-align 

-mno-code-allgn 

-mic-compat 

-mic2.0-compat 

-mic3.0-compat 

-masm-compat 

-mintel-asm 

-mstrict-align 

-mno-strict-align 

-mold-align 



Assume the defaults for the machine typeepu-type for instruction and addressing-mode 

availabi I ity and alignment. The default epu- type is kb; other choicesareka, me, ca, et, sa, and sb. 

The -mnumerics option indicates that the processor does support floating-point instructions. 

The -msoft-fioat option indicates that floati ng-point support should not beassumed. 

Do (or do not) atterri ptto alter leaf proceduresto be callable with the bai instruction aswell as 

cai i . This wi II result in more efficient code for explicit callswhen the bai instruction can be 

substituted by the assembler or linker, but less efficient code in other cases, such ascalls via 

function pointers, or using a linker that doesn't support this optimization. 

Do(ordo not) makeadditional attempts (beyond thoseof themachine-independent portions 

of thecompiler) to opti m i ze tai I - recu rsi ve calisi nto branches. You may not want to do this 

because the detection of cases where this isnot vai id is not totally complete. The default is 

-mno-tail-call. 

Assume (or do not assume) that the use of acomplexaddressing modeisa win on this i mple- 
mentation of the i960. Complexaddressing modes may notbeworthwhileon the K-series, but 
they defi nitely areon the C-series. The default iscurrently -mcompiex-addr for ali processors 
excepttheCB and CC. 

Align codeto 8-byte boundariesfor faster fetching (or don't bother). Currently turned on by 
default for C-series implementationsonly. 
E nable compati bi lity with iC 960 v2.0 or v3.0. 



E nable compati bi lity with the iC 960 assembler. 
D o not permit (do permit) unaligned accesses. 

Enablestructure-alignment compati bi lity with I ntel's gcc rei ease versi on 1.3 (based on gcc 
1.37). Currently this isbuggy in that #pragma align 1 isalwaysassumed aswell, and cannot be 
turned off. 
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These-m options are defi ned fortheD EC Alpha implementations: 

-mno - sof t -f ioat U se (do not use) the hardware f loati ng-poi nt i nstructions for f loati ng-poi nt operations. W hen 

-msoft-fioat -msoft-fioat isspecified, functions in ìibgcd.c will beused to perform floati ng-point 

operations. Unlessthey arereplaced by routinesthat emulate thefloating-point operations, or 
compiled in such away asto cali such emulati onsroutines, these routines will issuefloating- 
point operations. If you arecompilingforan Alpha withoutfloating-point operations, you 
must ensurethat the library is bui It so as not to cali them. 

N otethat Alpha implementations without fi oati ng-point operations are required to have 
floating-point regi sters. 

-mfp-reg, -mno-fp-regs G enerate code that uses (does not use) thefloati ng-point regi ster set. -mno-fp-regs implies 

-msoft-fioat. If thefloating-point regi ster set isnot used, floating-point operandsare passed in 
integer regi sters as if they were i ntegers and floating-point results are passed in $0 instead of $to. 
Thisis a nonstandard calling sequence, so any function with a floati ng-point argument or 
return value called by code compiled with -mno-fp-regs must also be compiled with that 
option. 

A typical useof thisoption isbuilding a kernel that does not use, and henceneed notsaveand 
restare, any floating-point registers. 

These additional options are availableon System V Release4 for compati bili ty with other compi lerson thosesystems: 

-G On SVr4 systems, gcc accepts the option -g (and passes it to the system linker), for compati bi I- 

ity with other compilers. H owever, wesuggestyou use-symboiic or -snared as appropriate 
instead of supplying linker optionson thegcc command line. 

-Qy Identify the versions of each tool used by the compi ler, in an .ident assembler di recti ve in the 

output. 

-Qn Refrainfrom adding .ident directives to theoutput file (this is the default). 

-YP.di rs Search the directories di rs, and no others, for I i brari es specified with -1. You can separate 

directory entries in di rs from oneanotherwith colons. 
-Ym.di r Look in the directory di r to find theM 4 preprocessor. The assembler uses this option. 

CODE GEN ERATIO N OPTIONS 

These machine-independent options control the interface conventions used in code generation. 

M ost of them begin with -f. These options haveboth positive and negativeforms; the negative form of -ffoo would be-fno- 
foo. In thefollowing table, only oneof the forms is listed — theonewhich isnot the default. You can figure out the other 
form by either removingno- or adding it. 

-fnonnuii-objects Assume that objects reached through references are not nuli (C++ only). 

Normally, GNU C++makes conservative assumptionsabout objects reached through 
references. For example, the compi ler must check that a isnot nuli in code like thefollowing: 

obj &a = g (); a.f (2); 

C hecking that references of this sort havenonnull values requires extra code, however, and it is 

unnecessary for many programs. You can use -fnonnuii -objects to om it the checks for nuli, if 

your program doesn't require checking. 
-fpcc-struct-return U se the same convention for returning struct and union values that isused by the usuai C 

compi ler on your system. This convention is less efficient for small structures, and on many 

machines it failsto bereentrant; but it hastheadvantageof allowing i ntercal labi I ity between 

gcc-compiled code and pcc-compiled code 
-freg-struct-return U se the convention that struct and union values are returned in registerswhen possi ble This is 

more efficient for small structures than -fpcc-struct-return. 

If you specify neither -fpcc-struct-return nor -freg-struct-return, G N U C C defaults to 
whichever convention is standard for the target. If thereis no standard convention, GNU CC 

defaults tO -fpcc-struct-return. 
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Allocate to an enum typeonly as many bytesasit needsfor the deci ared rangeof possible values. 
Specificali^ the enum typewill beequivalentto the smallest integer typethat hasenough room. 
Usethesamesizefor doublé asfortioat. 

Requeststhat the data and non-const variablesof this compilation beshared data rather than 
pri vate data. The disti nction makessenseonly on certain operati ng system s, whereshared data 
isshared between processesrunningthesame program, whileprivate data existsin onecopy per 
process. 

Allocate even uninitialized global variablesin thebss section of the object file, rather than 
generati ng them as common blocks. T his has the effect that if the same variable is declared 
(without extern) in two different compilations, you will get an errar when you link them. The 
only reason thismight beuseful isif you want to verify that the program will work on other 
systemswhich alwayswork thisway. 
lgnorethe#ident di recti ve. 

Do not output global i niti al izations (such asC-H-constructorsand destructors) in theform 
used by theGN U linker (on systemswheretheGN U linker is the standard method of handling 
them). Use this option when you want to use a non-GN U linker, which also requiresusingthe 
coiiect2 program to makesure the system linker includesconstructorsand destructors. 
(coiiect2 isincluded in theGN U CC di stributi on.) For systems that must use coiiect2, the 
compiler driver gcc isconfigured to do this automatically. 

Don't output a .size assembler di recti ve, or anything else that would cause troubleif the 
function issplit in the middle, and thetwo halves areplaced at locationsfar apart in memory. 
This option isused when compili ngcrtstuft.c; you should not need to use it for anything else. 
Put extra commentary information in thegenerated assembly codeto makeit morereadable. 
This option isgenerally only of useto thosewho actually need to read thegenerated assembly 
code (perhaps while debugging the compiler itself). 
Considerali memory referencesthrough pointersto be volatile. 
Considerali memory referen cesto extern and global dataitemsto be volatile. 
If supported for the target machines, generate position-independent code, suitablefor use in a 
shared library. 

If supported for the target machine, emit position-independent code, suitablefor dynamic 
linking, even if branches need largedisplacements. 

Treat the regi ster named r e g asafixed register; generated code should never refer to it (except 

perhaps as a stack pointer, frame pointer, or in som e other fi xed role). 

r e g must be the name of a register. T he register namesaccepted aremachine-specific and are 

defined in the register_names macro in the machine description macro file. 

This fi ag does not havea negati ve form, because it specifies a three-way choice. 

Treat the regi ster named r e g asan allocable register that isclobbered by function cai Is. It may 

be allocateci for temporariesorvariablesthat do not live acrossa cali. Functions compi led this 

way will notsaveand restare the register reg. 

Useof thisflagfor a register that hasafixed pervasi ve role in the mach ine'sexecution model, 

such asthestack pointer or frame pointer, will produce disastrousresults. 

This fi ag does not havea negati ve form, because it specifies a three-way choice. 

Treat the regi ster named reg asan allocable register saved by functions. It may be allocateci even 

for temporariesorvariablesthat li ve acrossa cali. Functions compi led thisway will saveand 

resto re th e regi ster r e g if they use it. 

Useof thisflagfor a register that hasafixed pervasi ve role in the mach ine'sexecution model, 
such asthestack pointer or frame pointer, will produce disastrous results. 
A different sort of disaster will result from the use of this fi ag for a register in which function 
values may be returned. 

T his flag does not havea negati ve form, because it specifies a three-way choice. 
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#pragma interface 



PRAGMAS 

Two #pragma directives are supported for GN U C++to permit usi ng the sameheader file fortwo purposes: as a definiti on of 
interfacesto a given object class, and as the full definition of thecontentsof that object class 

(C-H-only.) U sethis directive in header fi les that define object classes, to save space in most of 
the object fi les that use thoseclasses. Normally, locai copiesof certain information (backup 
copiesof inline memberfunctions, debugging information, and the internai tablesthat 
implement virtual functions) must bekept in each object file that includes class definiti ons. You 
can usethispragmato avoid such dupli cati on. When a header fi le contai ni ng#pragma 
interface isincluded in a compilation, thisauxiliary information will not begenerated (unless 
themain input sourcefile itself uses#pragma impiementation). Instead, the obj ect files wi II 
contain referencesto beresolved at linktime. 

(C++only.) U sethis pragma in a main input fi le, when you want full output from included 
header files to begenerated (and madeglobally visible). The included header file, in turn, 
should use#pragma interface. Backup copiesof inline member functions, debugging informa- 
tion, and the internai tablesused to implement virtual functions are ali generated in implemen- 
tation file. 

If you use#pragma impiementation with no argument, it applies to an include fi le with thesame 
basenameasyour sourcefile; for example, in aiiciass.cc, #pragma impiementation by itself is 
equivalent to #pragma i-piementation "aiiciass.h". U se the stri ng argument if you want a 
single implementation fileto include code from multiple header files. 
There is no way to split up the contents of a single header file into multiple implementation 
files 



#pragma implementation 
#pragma implementation 

"obj ects .h" 



FILES 

file.c 

file.h 

file.i 

file.C 

file. ce 

file.cxx 

file.m 

file.s 

file.o 

a.out 

TMPDI R/cc 

LI BDI R/cpp 

LI BDI R /ed 

LI BDI R/cc1plus 

LI BDI R/collect 

LI BDI R/libgcc.a 

/lib/crt[01n] .0 

LI BDI R/ccrt0 

/lib/libc.a 

/usr/include 

LI BDI R/include 

LI BDI R /g++-include 



C sourcefile 

C header (preprocessor) file 
Preprocessed C sourcefile 
C++ sourcefile 
C++ sourcefile 
C++ sourcefile 
Objective-C sourcefile 
Assembly language file 
Object file 
Link edited output 
Temporary files 
Preprocessor 
Compiler for C 
CompilerforC++ 

Linker front end needed on somemachines 
gec subroutine library 
Startup routine 

Additional startup routinefor C ++ 
Standard C library; seeintro(3) 
Standard directory for #inciude files 
Standard gec directory for «include files 
Additional g++ directory for #inciude 



LI BDI R iSUSUally /usr/local/lib/machi ne /versi on. 



tmpdi r comes from theenvironment vari ableTMPDiR (defauit /usr/tmp if available; otherwise, /tmp.). 



gemtopbm 

SEEALSO 

cpp(l), as(l), ld(l), gdb(l), adb(l), dbx(l), sdb(l) 
gcc, cpp, as, ld, and gdb entries in info. 

Usingand P orti ng G N U CC (forversion 2.0), Richard M . Stallman;TheC Preprocessor, Richard M . Stallman; Debugging 
with GDB: theGN U Source-Levd Debugger, Richard M . Stallman and Roland H . Pesch; Usingas theGN U Assembler, Dean 
Elsner, Jay Fenlason & friends; ld: theGNU Linker, Steve Cham beri ai n and Roland Pesch. 

BUGS 

For instructionson reporti ng bugs, seetheGCC manual. 
COPYING 

Copyright 1991, 1992, 1993 Free Software Foundation, Inc. 

Permission isgranted to makeand di stri bute verbati m copiesof this manual provided thecopyright noticeand this 
permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof this manual under the conditions for verbati m copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof this manual into another language, under the precedi ng 
conditions for modifi ed versions, except that this permission notice may beincluded in translationsapproved by the Free 
Software Foundation instead of in the originai English. 

AUTHORS 

See theGNU CC manual for the contri butorsto GNU CC. 

GNU Tools 13 October 1993 

gemtopbm 

gemtopbm— Converta GEM IMG file into a portable bitmap 
SYNOPSIS 

gemtopbm [ -d] [ gemfile ] 

D ESC RIFIO N 

ReadsaGEM IMG fileasinput. Readsfrom stdin if input file isomitted. Produces a portable bitmap as output. 
0PTI0NS 

-d Produce output describi ng the contentsof the IM G file. 

BUGS 

D oes not support files contai ni ng more than one piane. 
SEEALSO 

pbmtogem(l), pbm(5) 

AUTHOR 

Copyright© 1988 D iomidisD . Spi nellis (dds@cc . ic.ac.uk). 

11 July 1992 
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geqn 

geqn— Format equationsfor troff 
SYNOPSIS 

geqn [ -rvCNR ] [-de c ][-Tname ] [ -Md i r ][-fF ][-sn ][-pn ][-mn ] [ f i I e s ... ] 

D ESC RIFIO N 

Thismanual page describes the GN U version of eqn, which ispart of thegroff document formatti ng system, eqn compiles 
descriptionsof equationsembedded within troff input fi lesi nto commands that areunderstood by troff. N ormai ly, it 
should beinvoked using the -e option of groff. Thesyntax isquitecompatiblewith U N IX eqn. The output of GN U eqn 
cannot beprocessed with U N IX troff; it must beprocessed with GN U troff. If no filesaregiven on thecommand line the 
standard input wi II beread. A filenameof - will cause the standard inputto beread. 

eqn searches for the file eqnrc using the path .:/usr/iib/groff/tmac:/usr/iib/tmac. If it exists, eqn wi II process it beforethe 
other input fi les. The-R option preventsthis. 

GNU eqn does not provi de the functionalityofneqn: it doesnotsupport low-resolution, typewriter-likedevices(although it 
may work adequately for very si mple input). 

OPTIONS 



-c Recognize .eq and .en even when followed by acharacter other than space or newline. 

-N Don't allow newlines within delimiters. This option allowseqn to recover better from missing closing 

delimiters. 

-v P ri nt the version number. 

-r Only onesizereduction. 

-mn The minimum point-sizeisn. eqn will not reducethesizeof subscriptsor superscriptsto a smaller size 

than n. 

-marne The output is for device na me . T he only effectof this i sto define a macro name with avalueof 1 . Typically, 

eqnrc will usethisto provide definitions appropriatefor the output device. T he default output device isps. 
-Md i r Search dir for eqnrc before the default di rectories. 

-R D On't load eqnrc. 

-fF Thisisequivalentto agfontF command. 

-sn Thisisequivalentto agsizen command. This option isdeprecated. eqn will normally set equationsat 

whateverthecurrentpointsize iswhen theequation isencountered. 
-pn Thissaysthat subscriptsand superscripts should ben points smaller than thesurrounding text. This option 

isdeprecated. Normally, eqn makessets subscriptsand superscripts at 70 percent of the size of the 

surroundingtext. 

USAGE 



Only the differences between GNU eqn and UN IX eqn aredescribed here 

Mostof thenew featuresof GNU eqn arebased on TeX. T here are some referencesto the differences between TeX and 
GNU eqn asfollows; thesemay safely beignored if you do not knowTeX. 

AUTOMATIC SPACING 

eqn giveseach component of an equation atype, and adjusts the spacing between com ponents using that type. Possibletypes 
are 

ordinary An ordinary character such as 1 orx 

operator A large operator such as ; 

binary A binary operator such as + 

relation A relation such as = 
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opening An opening bracket such as ( 

ciosing A dosi ng bracket such as ) 

punctuation A punctuation character such as , 

inner A subformula contai ned within brackets 

suppress Spacing that suppresses automatic spacing adjustment 

Components of an equation getatypein oneof two ways: 

typete T his yields an equation component that containse butthat hastypet, wheret isoneof thetypes 

mentioned previously. Forexample, timesisdefined as 

type "binary" \(mu 

Thenameof thetypedoesn't haveto bequoted, but quoti ng protectsfrom macro expansion. 
chartypettext U nquoted groupsof charactersare split up into individuai characters, and the type ofeach characteris 
looked up; thischanges the type that isstored for each character; itsays that the characters in text from 
now on havetypet . For example 

chartype "punctuation" 

would make the characters . , ; : have type punctuation whenever they subsequently appeared in an 
equation. The type t can also beletter or digit; in thesecases, chartype changes the font type of the 
characters. Seethe'Tonts" section, later in thismanual page. 



new primitive; 

e 1 smallovere 2 
vcentere 

elaccente2 

eluaccente2 

splittext 
nosplitt ext 



Thisissimilarto over; smaiiover reducesthesizeof ei and e 2 ; it also putslessvertical space between e 1 or 
e 2 and thefraction bar. The over primitive correspondsto the\over primitive in display styles; smaiiover 
correspondsto Wer in nondisplay styles. 

T his vertically centerse about themath axis. Themath axis is the vertical position aboutwhich characters 
such as+ and - arecentered; also it is the vertical position used for the bar of fractions. For example, sum is 
defined as 

{type "operator" vcenter size -+5 \(*S } 

T h i s sets e 2 asan accent over e 1 . e2 isassumedto beat the correct height fora lowercaseletter; e2 will be 
moved down accordi ng if e 1 istaller or shorter than a lowercaseletter. Forexample, nat isdefined as 
accent {""" } 

dotdot, dot, tilde, vec, and dyad arealso defined using the accent primitive 

T h i s sets e 2 asan accent under ei. e2 isassumed to beat the correct height for a character without a 
descender; e 2 wi II be moved down if ei has a descender, utiide ispredefined using uaccent as a tilde accent 
below the basdi ne 

Thishasthesameeffect assimply text, but text isnot subject to macro expansion becauseit isquoted; 
text will be split up and thespacing between individuai characters will beadjusted. 
Thishasthesameeffect as text, but becausetext isnot quoted it will be subject to macro expansion; text 
will not besplitup and thespacing between individuai characters will not beadjusted. 
e opprime This isa variant of prime that acts asan operator on e .It produces a different result from prime in a case 

such asAopprimesubi : W ith opprime the 1 will betucked under the prime as a subscript to the a (asis 
conventional in mathematica! typesetting), whereaswith prime the 1 will beasubscriptto theprime 
character. The precedenceof opprime is the sameas that of bar and under, which is higher than that of 
everythingexcept accent and uaccent. In unquoted text, a 1 that is not thefirst character will betreated 

like opprime. 

speciaitext e This constructs a new object from e using agtroff(l) macro named t ext . When the macro iscalled, the 
stringes will contai n the output for e, and thenumber registersow, ah, ad, askern and eskew will contai n 
thewidth, height, depth, subscript kern, and skew of e. (T he subscript kern of an object says how much a 
subscript on that object should betucked in; the skew of an object says how far to the right of the center of 
the object an accent over the object should beplaced.) The macro must modify os so that itwill output 
the desi red result with itsorigin atthecurrent point, and increasethecurrent horizontal position by the 
width of the object. Thenumber regi sters must also bemodified so that they correspond to the result. 
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Forexample, suppose you wanted aconstructthatcancelsan expression by drawingadiagonal linethrough it: 

. EQ 

define cancel 'special Ca 1 
. EN 

.de Ca 

.ds 0s \Z , \\*(0s , \v , \\n(0du , \D , l \\n(0wu - \ \n(0hu - \ \n(0du 1 \v 1 \ \n(0hu ' 

Then you could cancel an expression U with cancei e. 

H ere'sa morecomplicated construct that drawsa box around an expression: 

.EQ 

define box 'special Bx' 
.EN 

.de Bx 

.ds 0s \Z'\h'1n'\\*(0s'\ 

\Z'\v'\\n(0du+1n'\D'l \\n(0wu+2n 0'\D'1 0 -\\n(0hu-\\n(0du-2n ' \ 
\D'l -\\n(0wu-2n 0 1 \ D ' 1 0 \\n(0hu+\ \n (0du+2n" \h ' \\n(0wu+2n 
.nr 0w +2n 
.nr 0d +1n 
.nr 0h +1n 



CUSTOMIZATION 

Theappearanceof equations iscontrolled by a large number of parameters. These can be set using the set command. 
setpn Thissetsparameterp to valuen; n isan integer. For example 

set x_height 45 

saysthat eqn should assume an x height of 0.45 ems. 

Possi ble parameters are asfollows. Valuesarein unitsof hundredthsof an em unlessotherwisestated. These descri ptions are 
intendedto be expository ratherthan definitive. 

eqn will not set anything ata smaller point sizethan this. Thevalueisin points. 
Thefat primitive emboldensan equation by overprintingtwo copi esof the equation horizontally 
offset by thisamount. 

A fraction bar will belonger by twi ce thisamount than the maximum of thewidthsof the 
numerator and denomi nator; in otherwords, i t will overhangthenumerator and denomi nator by 
atleast thisamount. 

When bar or under isapplied to a single eh aracter, the li ne will be this long. N ormally, bar or 
under producesalinewhoselength isthewidth of theobjectto which itapplies: in thecaseof a 
single eh aracter, thistendsto produce a line that lookstoo long. 

Extensibledelimiters produced with the left and right primitiveswill haveacombined height and 
depth of atleast this many thousandthsof twice the maximum amount by which thesubequation 
that the deli miters enclose extends away from the axis. 

Extensibledelimiters produced with the left and right primitiveswill haveacombined height and 
depth not lessthan the differenceof twice the maximum amount by which thesubequation that 
the del i mi ters enclose extends away from the axi s and thi s amount. 
Thismuch horizontal space isinserted on each side of a fraction. 
Thewidth of subscriptsand superscriptsisincreased by thisamount. 
Thisamount of space isautomatically inserted after punctuation characters. 
Thisamount of space isautomatically inserted on either side of binary operators. 
Thisamount of space isautomatically inserted on either side of relations. 



mimmum^size 
fat_off set 

over_hang 
accent_width 
delimiter_f actor 
delimiter shortfall 



null_delimiter_space 

script_space 

thin_space 

medium_space 

thick_space 



geqn 



FI 



Theheight of lowercaseletterswithout ascenders such asx. 

T he height above the baseline of the center of characters such as + and -. It is important that this 
value be correct for the font you are usi ng. 

Thisshould setto thethicknessof the\(ru character, or thethicknessof horizontal lines produced 
withthe\D escape sequence. 

The over command wi II shift up the numerator by at least this amount. 
The smaiiover command wi II shift up the numerator by at least this amount. 
The over command wi 1 1 shift down the denomi nator by at least this amount. 
The smaiiover command will shift down the denomi nator by at least this amount. 
N ormally superscriptswill beshifted up by at least this amount. 

Superscriptswithin superscripts or upper limitsor numeratore of smaiiover fractionswill beshifted 
up by at least this amount. This is usually lessthan supi. 

Superscriptswithin denomi nators or square roots or subscriptsor lower limitswill beshifted up by 
at least this amount. This is usually lessthan sup2. 
Subscriptswill normally beshifted down byat least this amount. 

When thereisboth a subscript and a superscript, the subscript will beshifted down byat least this 
amount. 

Thebaselineof a superscript will beno morethan this amount below the top of theobject on 
which the superscript is set. 

T he baselineof a subscript will be at least this much below the bottom of the object on which the 
subscri pt i s set. 

Thebaselineof an upper limitwill beat least this much above the top of the object on which the 
limit isset. 

Thebaselineof a lower limitwill beat least this much below the bottom of theobject on which the 
limit isset. 

The bottom of an upper limit will beat least this much above the top of theobject on which the 
limit isset. 

The top of a lower limitwill beat least this much below the bottom of theobject on which the 
limit isset. 

Thismuch vertical space will beadded above and below limits. 

Thebaselinesof therowsin a pile or matrixwill normally be this far apart. In most cases, this 
should be equal to the sum of numi and denomi . 

Themidpoint between the top baseline and the bottom baseline in a matrix or pi le will beshifted 
down by this much from theaxis. In most cases, thisshould be equal to axisjeight. 
Thismuch space will beadded between columnsin a matrix. 
Thismuch space will beadded ateach si de of a matrix. 

If this is nonzero, li nes will bedrawn usi ng the \d escape sequence, ratherthan with theu escape 
sequence and the \(ru character. 

The amount by which theheight of the equation exceeds this will beadded as extra space before 
the line contai ni ng the equation (using \x.) The default value is 85. 

The amount by which thedepth of the equation exceeds this will beadded as extra space after the 
li ne contai ni ng the equation (using \x.) The default value is 35. 

If this is nonzero, then ndefine will behave li ke define and tdefine will beignored; otherwise, 
tdefine will behave li ke define and ndefine will beignored. The default value is 0. (Thisistypically 
changedtoi by theeqnrc filefor theascii and latini devices.) 

A more precise description of theroleof manyof these parameters can befound in Appendix H of TheTeXbook. 



x_height 
axis_height 

default_rule_thickness 

numi 

num2 

denoml 

denom2 

sup1 

sup2 

sup3 

subì 
sub2 

sup_drop 

sub_drop 

big_op_spacing1 

big_op_spacing2 

big_op_spacing3 

big_op_spacing4 

big_op_spacing5 
baseline_sep 

shif t_down 

column_sep 

matrix_side_sep 

draw_lines 

bodyheight 

body_depth 

nrof f 
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MACROS 

M acroscan takearguments. In a macro body, $ n wheren is between 1 and 9, will bereplaced by the nth argument if the 
macro iscalled with arguments; if there are fewer than n arguments, itwill bereplaced by nothing. A word contai ni ng a left 
parenthesiswherethepart of the word before the left parenthesishasbeen defined usi ng the define command will be 
recognized asa macro cali with arguments; charactersfollowing the left parenthesisup to a matching right parenthesiswill be 
treated ascomma-separated arguments; commas inside nested parenthesesdo not termi nate an argument. 

sdefinename xanyt h ngx T his is li ke the define command, but name will not berecognized if called with arguments. 
inciudef i i e I nclude the contents of f i e. Lines of f i i e beginningwith .eq or .en will beignored. 

ifdefnamexanyt hi ngx I f n a me has been defined by define (or has been automatically defined because na me istheoutput 

device), processanythi ng; otherwiseignoreanythi ng. 

x can be any character not appearing in anythi ng. 

FONTS 

eqn normally uses at least two fontsto set an equation: an italicfontfor letters, and a Roman font for everything else The 
existinggfont command changes the font that isused as the itali c font. By default thisisi. The font that isused asthe 
Roman font can bechanged by using thenew grfont command. 

grfontf Set the Roman font to f . 

The itali c pri miti ve uses the current i tali c font set by gfont; the Roman primitive uses the current Roman font set by grfont. 
There isalso a new gofont command, which changes the font used by thebold primitive. If you only use the Roman, italic, 
and bold pri miti vesto changefontswithin an equation, you can changeall the fonts used by your equations just by using 
gfont, grfont, and gbfont commands. 

You can control which characters are treated as letters (and thereforeset in italic) by using the chartype command described 
earlier. A typeof letter will cause a character to be set in italic type. A typeof digit will cause a character to be set in Roman 
type. 

FILES 

/usr/lib/groff/tmac/eqnrc I n i ti al i zati On file 

BUGS 

I ni ine equations wi II be set at the pointsize that is current at the beginning of the i nput line. 
SEEALSO 

groff(l), gtroff(l), groff_font(5), TheTeXbOOk 

getlist 

getiist— Get a list from an N NTP server 
SYNOPSIS 

getlist [ -h host ][list [ pattern [ types ]]] 

D ESC RIFTIO N 

The getlist program obtains a list from an N NTP server and sends itto standard output. 

Theiist may beoneof active, active.times, distributions, Or newsgroups. Thesevalues request theactive(5), 
active.times, /news/lib/distributions, Or /news/lib/newsgroups files, respectively. 

If the-h flag isused, then the program connectsto the server on the specified host. The default isto connectto the server 
specified in theinn.conf(5) file. 



getopt 



I f the list parameter isactive, then the pattern and types parameters may Peused to I i mi t the output. When pattern is 
used, only active lines with groupsthat match accordi ng to wiidmat(3) areprinted. When types i salso given, only activelines 
that haveafourth field starti ng with a character found intypes areprinted. 

For example, the followi ng command will oPtain the one-l ine descri pti ons of ali newsgroups found on uunet: 

getlist -h news.uu.net newsgroups 

The followi ng line li sts ali groupswhere locai posti ngs are permitted, moderated, oraliased: 

getlist active '*' ym= 

N otethat the listi ng fi lesother than the active fi le isa common extension to theN NTP protocol and may not PeavailaPle 
on ali servers. 

HI STORY 

Written Py Landon Curt N oli (<chongoetoad.com>) for InterN etN ews. 
SEEALSO 

active(5), nnrpd(8), wildmat(3) 

getopt 

getopt— Parse command options 
SYNOPSIS 

set - 'getopt optstring $*' 

D ESC RIFIO N 

getopt isused to Preak up options in command lines for easy parsi ng Py shell procedures, and to check for legai options. 
optstring isastring of recognized option letters; seegetopt(3). If a letter isfollowed Py a colon, theoption isexpected to 
havean argument that may or may not Peseparated from it Py whitespace. The special option - - isused to delimit the end 
of the options. getopt will place - - in theargumentsat the end of the options, or recognizeit if used explicitly. The shell 
arguments($i $2 ...) are reset so that each option ispreceded Pya- and in itsown shell argument; each option argument 
isalso in itsown shell argument. 

EXAMPLE 

The followi ng codefragment showshow onemight process the arguments for a command that can taketheoptionsa and b, 
and theoption 0, which requiresan argument: 

set - 'getopt abo: $*' 

if test $? != 0 
then 



echo 'Usage: 
exit 2 



fi 

for i 
do 



case "$i" 
in 



-a| -b) 
-0) 

--) 



flag=$i; shift;; 
oarg=$2; shift; shift;; 
shift; break;; 



done 
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Thiscodewill accept any of thefollowing as equivalenti 

cmd -aoarg file file 

cmd -a -o arg file file 

cmd -oarg -a file file 

cmd -a -oarg - - file file 

SEEALSO 

sh(l), getopt(3) 

DIAGNOSTICS 

getopt printsan errar messageon the standard errar output when it encountersan option letter not included in optstring. 
HISTORY 

Written by H enry Spencer, working from a Bell Labsmanual page. Behavior believed identical to the Bell version. 

BUGS 

W hatever getopt(3) has. 

Arguments containing whitespace or embedded shell meta characters generally will not survive intact; thislooks easy to fix 
but isn't. 

The errar messageforan invalid option isidentified as comi ng from getopt rather than from the shell procedure containing 
theinvocation of getopt; this, again, is hard to fix. 

The precise best way to use the set command to set the arguments without disrupting thevalue(s) of shell options varies 
from oneshell version to another. 

21 junel993 

gif topnm 

gif topnm— C onvert a G I F fi le i nto a portable anymap 
SYNOPSIS 

giftopnm [ -verbose] [ -comments] [ -image N][GIFfile] 

D ESC RIFIO N 

Readsa GIF filefor input, and outputs portable anymap. 

OPTIONS 

-verbose Produces verbose output about the G I F fileinput. 

-comments 0 nly outputs G I F89 commentfields. 

-image 0 utputs the specified GIF image from the input G I F archive(whereN isi, 2, 20...). Normally, thereis 

onlyone image per file, so this option isnotneeded. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
BUGS 

Thisdoes not correctly handlethePlain Text Extension of the G I F89 standard, sincel did not haveany example input files 
containing them. 



gindxbib 



SEEALSO 

ppmtogif(l), ppm(5) 

AUTHOR 

Copyright © 1993 by D avid Koblas(kobias@netcom.com) 

29 September 1993 



gindxbib 

gindxbib— M ake inverted index for bibliographic database 
SYNOPSIS 

gindxbib [-vw] [ -c file] [ -d dir] [-f f il e ] [-h n] [ — ± stri ng ] 
[-k n] [-1 n] [-n n] [-0 file] [-t n] [fi [ e r a me ...] 

D ESC RIFIO N 

gindxbib makesan inverted index for the bibliographic databasesin f i i e n a me . . . for usewith grefer(l), giookbib(l), and 
ìkbib(l). The index wi II benamed fi i e n a me . ±; the index iswritten to atemporary filewhich isthen renamed to this. If no 
filenamesaregiven on thecommand linebecausethe-f option has been used, and no -o option isgiven, the index wi II be 
named md.i. 

Bibliographic databasesaredivided into recordsby blank lines. W ithin a record, each fields starts with a% character at the 
beginning of a line. Fields havea one-letter namethat follows the% character. 

Thevaluesset by the-c, -n, -1, and -t opti ons are stored in the index; when the index issearched, keyswill bediscarded and 
truncated in a manner appropri ateto theseoptions; the originai keyswill beused for verifying that any record found using 
the index actually contai ns the keys. This meansthat a user of an index need not know whether theseoptions were used in 
thecreation of theindex, provided that not ali the keys to besearched forwould havebeen discarded during indexingand 
that the user suppliesat least thepart of each key thatwould have remai ned after bei ng truncated during indexing. The value 
set by the-i option isalso stored in the index and will beused in verifying records found using theindex. 



OPTIONS 

-v P ri nt the versi on number. 

-w Indexwholefiles. Each file is a separate record. 

-cf i 1 e Read the listof common wordsfrom file instead of /usr/nb/groff/eign. 

-dd i r Use di r as the pathname of the current working directory to storein theindex, instead of thepath printed 

by pwd(l). Usually di r will bea symbolic link that pointsto the directory printed by pwd(l). 

-ff i 1 e Read the fi lesto beindexed from file. I f fi le i s —, fi I es will beread from the standard input. The -f option 

can be given at most once 

-istr i ng Don't index the contents of fields whose names are in s t r i ng. Initially, st ri ng ìsxyz. 

-hn U se the first prime greaterthan orequal to n forthesizeof thehash table. Larger valuesof n will usually 

makesearchingfaster, but will make the index larger and gindxbib use more memory. Initially, n is 997. 

-kn Useatmostn keys per input record. Initially, n is 100. 

-in Discard keys that are shorterthan n. Initially, n is 3. 

-nn Discard then most common words. Initially, n islOO. 

-obasena me The index should be named b a s e na me . i. 

-tn Torneate keys ton. Initially, n is 6. 
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FILES 

fi I e n a me . i 
Ind.i 

/usr/lib/groff /eign 
indxbibXXXXXX 

SEEALSO 

grefer(l), lkbib(l), glookbib(l) 

Groff Veraon 1.09, 16 Aprii 1993 



Index 

Default index name 
List of common words 
Temporary file 



glookbib 

giookbib— Search bibliographic databases 
SYNOPSIS 

glookbib [ -v ] [ -±s t r i n g ][-tn ] fi I e n a me ... 

D ESC RIPTIO N 

glookbib prints a prompt on the standard errar (unless the standard input is nota terminal), readsfrom the standard input a 
li ne contai ni ng a set of keywords, searches the bibliographic databasesf i ename . . . for references contai ni ngthosekeywords, 
prints any references found on the standard output, and repeatsthisprocessuntil the end of input. Foreach database 
fi i ename to besearched, if an index fi i ename .i created by gindxbib(l) exists, then itwill besearched instead; each index can 
cover multiple databases. 

OPTIONS 

-v P ri nt the versi on number. 

-is t r i ng When searchi ng files for which no index exists, ignora the contentsof fieldswhosenamesareinstr ng. 

-tn Only requirethefirstn characters of keys to begiven. Initially, n ise. 

FILE 

fi I ename. i Indexfiles 

SEEALSO 

grefer(l), lkbib(l), gindxbib(l) 



gnroff 

gnroff— Emulate nroff COmmand with groff 

SYNOPSIS 

gnroff [ -fi ] [-i ] [-mname ] [ -nn u m ] [ -ol i s t ] [-rcn ] [-Tname ] [f i I e. . . ] 



DESCRIPTION 

The gnroff script emulatesthe nroff command usi ng groff. The -t option with an argument other than ascii and latini 
will beignored. The-n option isequivalentto thegrotty -n option. The-i, -n, -m, -o, and -r opti onshave the effect 
described in gtroff(l). In addition, gnroff silently ignoresoptionsof -e, -q, or -s. 




SEEALSO 

groff(l), gtroff(l), grotty(l) 

Groff Version 1.09, 17 May 1993 

gouldtoppm 

gouidtoppm— C onvert G ould scanner fi le into a portable pixmap 
SYNOPSIS 

gouldtoppm[goul df il e ] 

DESCRIPTION 

Reads a file produced by the G ould scanner as input. Produces a portable pixmap as output. 
SEEALSO 

ppm(5) 

AUTHOR 

Copyright© 1990 by Stephen Paul Lesniewski 

20 May 1990 

gpic 

gpic— Compi le picturesfortroff orTeX 
SYNOPSIS 

gpic [ -nvC ] [f Menarne ... ] gpic -t [ -cvzC ] [f i I e n a me ... ] 

DESCRIPTION 

Thismanual page describes the GN U version of pie, which ispart of thegroff document formatti ng system, pie compiles 
descriptionsof picturesembedded within troff orTeX input files into commandsthat areunderstood byTeX ortroff. 
Each picture starts with a line beginning with .ps andendswith a line beginning with .pe. Anything outsideof .ps and .pe 
is passed through without change. 

It istheuser's responsi bility to provide appropri atedefinitionsof the ps and pe macros. W hen themacro package bei ng used 
doesnot supply such definitions (for example old versi onsof-ms), appropri ate defini ti onscan beobtained with -mpic: These 
will center each picture. 

OPTIONS 

Optionsthatdo nottakeargumentsmay begrouped behind a single-. The special option — can beused to mark the end of 
theoptions. A filenameof - refersto the standard input. 

-c Recognize .ps and .pe even when followed by acharacter otherthan space or newline. 

-n Don't use thegroff extensionsto thetroff drawing commands. You should usethis if you areusing a 

postprocessorthat doesn't support these extensions. The extensions are described in groff _out(5). The-n option 

also causes pie not to usezero-length linesto draw dotsin troff mode, 
-t TeX mode. 

-e Be more compati ble with tpic. Implies-t. Lines beginning with n are not passed through transparently. Lines 
beginning with . are passed through with theinitial . changedto\.A linebeginningwith .ps isgiven special 
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treatment: Ittakesan optional integer argument specifying the linethickness(pen size) in milli-inches; a missing 
argument restorestheprevious linethickness; the default linethickness is 8 milli-inches. The line thicknessthus 
speci fi ed takeseffect only when a nonnegative li ne thicknesshasnot been specified by useof thethickness 
attributeor by setti ng the ìinethick variable. 



-Tdev Generate output for the troff devicedev . Thisisunnecessary becausethetroff output generated bypic isdevice- 



Thissection descri bes only the differences between GNU pie and the originai versi on of pie. M any of thesedifferencesalso 
applyto newer versionsof UNIX pie. 



mode isenabled by the-t option. In mode, pie will define a vbox called ngraph for each picture. You must yourself print that 
vbox using, forexample, the command: 

\centerline{\box\graph} 

Actually, si nce the vbox hasa height of zero, thiswill produce slightly morevertical space above the picture than below it, the 
line 

\centerline{\raise 1em\box\graph} 

would avoid this. 

You must use a driver that supportsthetpic specials, version 2. 

Lines beginningwith \arepassed through transparently; a% isadded to the end of thelineto avoid unwanted spaces. You 
can safely use this featureto changefontsorto changethevalueof \baseiineskip. Anything elsemay well produce undesir- 
ableresults; useatyourown risk. Lines beginningwith aperiod arenot given any special treatment. 



-v Print the version number. 

-z InTeX modedraw dots using zero-length lines. 

Thefollowing options supported byother versionsof pie areignored: 
-D Drawall linesusingthe\Descapesequence. pie alwaysdoes this. 



independent. 



USAGE 



mode 



COMMANDS 

for vari a b I e = ex pr 1 to e x p r 2 
by [ * ] e x p r 3 ] do X body X 
[Set variable to expr 1 



Whilethevalueof vari a b i e islessthan orequal to expr 2 , do body and increment 
variable by ex pr 3 ; if by is not given, i ncrement v a r i abi e by 1. If expr 3 is prefixed 
by * then vari ab e will instead bemultiplied by e x p r 3 . x can be any character not 
occurring in body. 

Evaluateexpr ; if it is nonzero, do f ■ tr ne; otherwise, do i f-f ai se. u can be any 
character not occurring in i f - t r u e . y can be any character not occurring in i f ■ fai se. 
Concatenate the arguments and print as a li neon stderr. Each arg must bean 
expression, aposition, ortext. This is useful for debugging. 
Concatenate the arguments and passthem through asa line to troff orTeX. Each 
arg must bean expression, a position, ortext. This hasa si mi lar effect to a line 
beginningwith . or \, but allowsthevaluesof variablesto bepassed through. 
Pass command to ashell. x can be any character not occurring in command. 
Includef i i ename at thispoint in the file. 

Thisconstructdoesbody once for each line of f i i ename; the I ine is split into blank- 
delimited words, and occurrencesof $ i in body, fon between 1 and 9, are replaced 
by the i -th word of the line If fi i ename is not given, lines are taken from thecurrent 
input up to .pe. If an untii clauseis specified, lines will beread only unti I a li ne the 
first word ofwhich isword; that linewill then be discarded. x can be any character 
not occurring in body. Forexample 



if expr then X i f - 1 r u e X 
[else Y i f-f al se Y ] 
print arg ... 



command arg 



sh X command X 



copy "f i I ename " 

copy [ "f i I ename " ] thru X body X 
[until "word"] 

copy [ " f i I e n a me " ] thru mac r o 
[until "word"] 




.PS 

copy thru % circle at ($1,$2) % until "END" 

1 2 

3 4 

5 6 

END 

box 

.PE 

isequivalentto 

.PS 

circle at (1,2) 
circle at (3,4) 
circle at (5,6) 
box 
.PE 

Thecommandsto be performed foreach linecan also betaken from a macro 
defined earl ier by giving the name of the macro as the argument to thru. 

reset variabiei, variabie2 ... Reset predefined vari ables va r a b i e i , vari a b i e 2 ... to their default values If no 

argumentsaregiven, reset ali predefined variablesto their default values. Notethat 
assigningavalueto scaie also causesall predefined variablesthat control dimensions 
to be reset to the r default values ti mes the new value of scale. 

plot expr rtext"] T his is a text object which is constructed by using as a format string for t e x t sprintt 

with an argument of expr . If text isomitted, a format string of %g isused. Attributes 
can bespecified in the sameway asfora normal text object. Bevery careful thatyou 
speci fy an appropriate format string; pie doesonly very limited checkingof the 
string. This is deprecateci in favor of sprintt. 

vari abi e : =e x p r T his is simi lar to = exceptvari abi e mustalready be defined, and thevalueof 

var i abi e will bechanged only in theinnermost block in which itis defined. (By 
contrast, = defines thevari able in thecurrent block if it isnot already defined there, 
and then changes the value in thecurrent block.) 

Arguments of theform 

XanythingX 

are also allowed to beof theform: 

anything 

In this case anything can contain balanced occurrencesof and .br. Stringsmay contai n x or imbalanced occurrences of 

and .BR. 

EXPRESSIONS 

Thesyntaxfor expressi ons has been significante extended: 

x"y (exponentiation) 
sin(x ) 
cos(x ) 
atan2(y ,x) 
log(x ) (base 10) 

exp(x) (base 10, ie 1 0 1 - .4m 1 x 1 .4m' ) 
sqrt(x ) 
int(x ) 

rand() (return a random number between 0 and 1) 

rand(x) (return a random number between 1 and x; deprecated) 

max(el ,e2) 

min(el ,e2) 

!e 



Parti: U ser Commands 



e1 && e2 
e1 1 1 e2 
e1 == e2 
e1 1= e2 
e1 >= e2 
e1 > e2 
e1 <= e2 
e1 < e2 
"stri "=="str2" 
"stri " !="str2" 

String comparison expressionsmustbeparenthesized in somecontextsto avoid ambiguity. 
OTHERCHANGES 

A bareexpression, expr, isacceptableasan attribute; it isequivalent to di r expr, wheredi r isthecurrent direction. For 
example 

line 2i 

meansdraw a li ne 2 inches long in the current direction. 

The maximum width and height of thepicturearetaken from thevariablesmaxpswid and maxpsnt. Initially, thesehavevalues 
8.5 and 11. 

Scienti fi c notation isallowed fornumbers. For example 

x = 5e-2 

Text attri butes can becompounded. For example 
"foo" above ljust 
is legai. 

Thereisno limitto thedepth to which blockscan beexamined. For example 

[A: [B: [C: box ]]] Witti .A.B.C.sw at 1,2 
circle at last [ ] .A.B.C 

isacceptable. 

Arcsnow have compass pointsdetermined by thecircleof which the are isa part. 
Circlesand arcscan bedotted ordashed. In mode, splinescan bedotted ordashed. 

Boxescan haverounded corners. The rad attri butespecifies the radiusof the quarter-circlesat each corner. If no rad or diam 
attribute isgiven, a radiusof boxrad isused. Initially, boxrad hasa valueof 0. A boxwith rounded corners can bedotted or 
dashed. 

The .ps line can haveasecond argument specifying a maximum height for the picture. If the width of zero isspecified, the 
width will beignored in computing the scali ngfactor for the picture. N otethat GN U pie will always scale a picture by the 
sameamount vertically ashorizontally. Thisisdifferent from theD WB 2.0 pie, which may scalea picture by adifferent 
amount vertically than horizontally if a height isspecified. 

Each text object hasan invisible box associ ated with it. The compass points of a text object are determi ned by this box. The 
implicit motion associated with the object isalso determi ned by this box. Thedimensionsof this box aretaken from the 
width and height attri butes; if thewidth attribute is not supplied, then thewidth will betaken to betextwid; if the height 
attribute is not supplied, then the height will betaken to bethenumberof text stri ngs associated with the object ti mes 
textht. Initially textwid and textht havea valueof 0. 

In placeswhereaquoted text string can beused, an expression of theform: 

sprintf (f or ma t ,ar g , . . . ) 




can also beused; thiswill produce the arguments formattai accordi ng to f or ma t , which should bea stri ng asdescribed in 
printf(3), appropri atefor the numberof arguments supplì ed, using only the e, f, g, or% format characters. 

Thethicknessof thelinesused to draw objectsi scontro II ed by theiinethick variable. Thisgives thethicknessof lines in 
pointa A negativevaluemeansusethedefaultthickness: in outputmode, thismeansuseathicknessof 8 milli-inches; in 
output modewith the -c option, thismeansusethelinethicknessspecified by .ps lines; in troff output mode, thismeans 
use a thickness proportional to thepoint size. A zero valuemeans draw the thinnest possi ble line supported by the output 
device Initially, it hasavalueof -1. Thereisalso a thick[ness] attribute. Forexample, 

circle thickness 1 .5 

would draw a ci relè using a line with a thickness of 1.5 points. Thethicknessof lines isnotaffected by the valueof the scaie 
variable, nor by thewidth or height given in the .ps line. 

Boxes (includi ng boxeswith rounded corners), circles, and ellipsescan be fi lied by giving then an attribute of mi[ed]. This 
takesan optional argument of an expression with a valuebetween 0 and 1; 0 will fili it with white 1 with black, valuesin 
between with a proportionally gray shade. A valuegreater than 1 can also beused: thismeansfill with theshadeof gray that 
iscurrently being used fortext and lines. N ormally thiswill be black, but output devicesmay providea mechanism for 
changingthis. W ithoutan argument, then the valueof the variable fiiivai will beused. Initially, thishasa valueof 0.5. The 
invisible attribute does not affect thefilli ng of objects. Any text associateci with a fi lied objectwill beadded after the object 
hasbeen fi II ed, so that the text will not beobscured by the fi 1 1 i ng. 

Arrowheadswill bedrawn assolid triangles if thevari able arrowhead isnonzero and either modeisenabled orthe-x option 
hasbeen given. Initially, arrowhead hasavalueof 1. 

The troff output of pie is device-i ndependent. The -t option isthereforeredundant. AH numbersaretaken to bein inches; 
numbersarenever interpreted to beintroff machineunits. 

Objects can havean aiigned attribute. Thiswill only work when the postprocessor isgrops. Any text associated with an 
object having the aiigned attribute will berotated about the center of the object so that it is aiigned in the direction from the 
start pointto the end pointof the object. N ote that this attribute will haveno effectfor objects whose start and end points 
arecoincident. 

In placeswhere ntr, isallowed, e x p r 'th is also allowed. N ote that th isasingletoken: no space is al lowed between the 1 and 
theth. Forexample, 

fori =1 to 4 do{ 

line from 'i'th box.nw to 'i+1'th box.se 
} 

FILE 

/usr/iib/groff /tmac/tmac.pic Sam pi e defi ni ti ons of the PS and PE macros. 
SEE ALSO 

gtroff(l), groff_out(5), tex(l) 

T PIC : PIC for AT&T Bell Laboratories, Computing Sci enee Technical Report N 0. 116, PIC — A Graphics Language for 
T ypesetti ng. (This can beobtained by sending an e-mail messageto netiib@research.att.com with a body of "send 116 from 
research/cstr.") 

BUGS 

Input characters that are il legai for groff (thosewith ASCII codeO or between 013 and 037 octal or between 0200 and 0237 
octal) arerejected even in mode. 

T he interpretation of mivai isincompati ble with the pie in lOth edition U N IX, which interprets 0 as black and 1 as white. 
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gprof 

gprof— Display cali graph profiledata 
SYNOPSIS 

gprof [ -abcsz ] [ -ej-E name ] [-fj-F name ][-k f r o mn a me tonarne ] [ objfile [ gmon.out ]] 

D ESC RIPTIO N 

gprof produce an execution profileof C, Pascal, or Fortran77 programs. Theeffect of cai led routinesis incorporate^ in the 
proti le ofeach Caller. The proti le data istaken tram the cali graph proti le fi le (gmon.out default), which iscreated by programs 
that are compiled with the -pg option of cc(l), pc(l),and f 77(1). The -pg option also links in versionsof the library routines 
that arecompiled for profiling. gprof readsthegiven object fi le (the default isa.out) and establishes the relation between its 
symbol tableand the cali graph proti le from gmon.out. If morethan one profile file isspecified, the gprof output shows the 
sum of the proti le informati on in the given profile fi les. 

gprof calculatestheamount ottime spent in each routine. N ext, thesetimesarepropagated along the edgesof the cali graph. 
Cyclesarediscovered, and callsinto a cyclearemadeto sharethetimeof thecycle. The first listing shows thefunctions 
sorted accordingto thetimethey represent, includi ng the time of thei r cali graph descendants. Below each function entry is 
shown its (direct) cali graph children, and how theirtimesarepropagated to thisfunction. A similar display above the 
function shows how thisfunction'stimeand the ti me of its descendants ispropagated to its (direct) cali graph parents. 

Cycles are also shown, with an entry for thecycle as a whole and a listing of themembersof thecycle and their contri butions 
to thetimeand cali countsof thecycle. 

Second, a fiat profi le is given, similar to that provi ded by prof(l). This listing gives the total execution times, the cali counts, 
the ti me in milliseconds, the cali spent in theroutineitself, and the ti me in m i 1 1 i seco n ds th e cai I spent in the routine itself, 
including its descendants. 

Finally, an index of thefunction namesisprovided. 

OPTIONS 

T he followi ng opti ons are available: 

-a Suppresses the printing of statically declared functions. If this option is given, ali relevant information 

about the stati c function (forexample, timesamples, Calisto other functions, callsfrom other 
functions) belongsto thefunction loaded just before the stati c function in the objf ile file. 

-b Suppresses the printing of adescription of each field in the profi le. 

-c Thestatic cali graph of the program isdiscovered by a heuristic that examinesthetext space of the 

object file. Static-only parents or children are shown with cali countsof 0. 

-e name Suppresses the printi ng of the graph profile entry for routine name and ali its descendants (unlessthey 

have other ancestorsthat aren't suppressed). M orethan one -e option may be given. 0 nly one name 
may be given with each -e option. 

-e name Suppresses the printing of thegraph profileentry for routine name (and its descendants) as -e, 

previ ously and also excludesthetimespent in name (and its descendants) from the total and percentage 
ti me computati ons. (For example, -e mcount -e mcieanup is the default.) 

-f name P ri nts the graph profile entry of only the specified routi ne n a me and its descendants. M orethan one -f 

option may be given. Only onename may be given with each -f option. 

-f name Prints the graph profile entry of only the routine na me and its descendants (as-f, previously) and also 

usesonly thetimesof theprinted routi nesin total time and percentage computations. M orethan one 
-f option may be given. Only onename may be given with each -f option. The -f option overridesthe 
-e option. 

-k fromname tonarne Will delete any arcs from routinef romname to routi ne t ona me . This can beusedto break un desi red 

cycles. M orethan one-k option may be given. Only one pai r of routine names may be given with each 
-k option. 
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-s A prof ile fi le gmon.sum isproduced thatrepresentsthesum of the profi le information in ali the specified 

profilefiles. This summary profile file may begiven to later executionsof gprof (probably also with an 
-s) to accumulate profi le data across several runsof an objf ne file 

-v P ri nts the versi on numberfor gprof, andthen exits. 

-z D isplaysroutinesthat havezero usage(asshown by cali countsand accumulated ti me). Thisisuseful 

with the-c option for discovering which routineswerenever cali ed. 

FILES 

a.out The name list and text space 

gmon.out D ynamic cali graph and profile 

gmon.sum Summarized dynamic cali graph and profile 

SEE ALSO 

monitor(3), profil(2), cc(l), prof(l) 

"An Execution Profiler for M odular Programs," by S. Graham, P. Kessler, M . M cKusick; Software- Practiceand Experience, 
Voi. 13, pp. 671-685, 1983. 

"gprof: A Cali Graph Execution Profiler," by S. Graham, P. Kessler, M . M cKusick; Proceedingsof theSI G PLAN '82 
Symposium on Compiler Construction, SIGPLAN Notices, Voi. 17, No6, pp. 120-126, J une 1982. 

HI STORY 

gprof appeared in 4.2 BSD . 

BUGS 

The granulari ty of the sampling isshown, but rem ai ns statisti cai at best. W e assume that the ti me for each execution of a 
function can beexpressed by the total ti me for thefunction divided by thenumber of timesthefunction iscalled. Thus, the 
timepropagated along the cali graph arcsto thefunction's parents isdirectly proporti onal to thenumber of timesthat are is 
traversed. 

Parents that are notthemselvesprofiled will havethetimeof their profiled children propagated to them, but they wi II appear 
to bespontaneously invoked in thecall graph listi ng, and will not have their ti me propagated further. Similarly, signal 
catchers, even though profiled, will appear to bespontaneous(although for moreobscurereasons). Any profiled children of 
signal catchers should have their ti mes propagated properly, unless the signal catcherwas invoked duringtheexecution of the 
profiling routine in which case ali islost. 

The profiled program must cali exit(2) or return normally for the profiling information to besaved in the gmon.out file. 

29 January 1993 

grefer 

grefer— Preprocess bi bli ographic referencesfor groff 
SYNOPSIS 

grefer [ -benvCPRS] [ - a n] | - c fi e I d s ] [-f n] [-i fi e I d s ] | - k fi e I di [-1 m,n] [-p f i I errarne] [ -s f i e I d s ] [-t n] [-B 
field.macro] [f I errarne . . .] 

D ESC RIFIO N 

ThisfiledocumentstheGN U versi on of refer, which ispart of the groff document formatti ng system, refer copi es the 
contentsof f i i e n a me . . . to thestandard output, except that lines between .[and . ] are interpreted ascitations, and lines 
between .ri and .R2 are interpreted ascommandsabout how citations areto beprocessed. 
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Each citation specifies a reference. The citati on can specify a referencethat is contai ned in a bibliographic database by giving 
a set of keywords that only that reference contai ns. A I ternati ve! y, it can specify a reference by supplyi ng a database record i n 
thecitation. A combination of these alternati ves is also possible. 

For each citation, refer can produce a mark in thetext. Thismark consistsof some label that can beseparated from thetext 
and from other labelsin variousways. For each reference, it also outputsgroff commands that can beused by a macro 
package to produce a formatted reference for each citation. The output of refer must therefore be processed using asuitable 
macro package. The-ms and -me macrosareboth sui table. The commands to format a citati on's reference can be output 
immediately after thecitation, orthereferencesmay beaccumulated, and the commands output at somelater point. If the 
referencesareaccumulated, then multi plecitationsof the same reference will produce a single formatted reference. 

Theinterpretation of linesbetween .ri and .R2 ascommandsisa new featureof GN U refer. Documentsmaking use ofthis 
featurecan stili be processed byUNIX refer just by addingthelines: 

.de R1 

• ig R2 

to thebeginningof thedocument. Thiswill cause troff to ignoreeverything between .ri and .R2. Theeffect of some 
commands can also beachieved by opti ons. These options are supported mainly for compati bility with UNIX refer. It is 
usually more convenient to use commands. 

refer generates .if lines so that filenames and linenumbers in messages produced by commands that read refer output will 
becorrect; it also interprets lines begi nni ng with .if so that filenames and linenumbers in the messages and .if lines that it 
produceswill be accurate even if the input hasbeen preprocessed by acommand such asgsoeiim(l). 

OPTIONS 

M ost options are equi valent to commands (for a description of these commands, see "Commands," later in thismanual 



page): 






-b 


no-label-in-text; no- 


label-in-reference 


-e 


accumulate 




-n 


no-def ault-database 




-C 


compatible 




-P 


move-punctuation 




-s 


label " (A.n ]Q) 1 , 1 


(D.y ] D) " ; bracket-! 


-an 


reverse An 




— cf i e I d s 


capitalize fi e 1 d s 




-fn 


label %n 




— if i e I d s 


search-ignore fi e 1 d s 




-k 


label L%a 




-kf i el d 


label f i el d%a 




-1 


label A.nD.y%a 




-lm 


label A.n+mD.y%a 




-l,n 


label A.nD.y-n%a 




-lm,n 


label A.n+mD.y-n%a 




-pf i 1 e n a me 


database f i 1 ena me 




-ss pec 


sort spec 




-tn 


search-truncate n 





These options are equi valent to the foli owing commands with theaddition thatthefilenames specified on thecommand line 
are processed as if they were argumentsto thebibiiography command instead of in thenormal way: 



-B Annotate X AP: no-label-in-reference 

-Bf i e I d .ma c r o Annotate f i e I d ma c r o ; no-label-in -reference 




Thefollowing options have no equivalent commands: 

-v Printtheversion number 

-R D on't recognize lines begi nning with .R1/.R2 

USAGE 

BIBLIOG RAPH IC DATABASES 

Thebibliographic database is a text file consisti ng of records separated by oneor moreblank lines. W ithin each record, fields 
start with a% at the beginningof aline Each field has a one-character namethat immediately follows the%. Itisbestto use 
only uppercaseand lowercaselettersforthenamesof fields. Thenameof thefield should befollowed by exactly onespace, 
and then bythecontentsof thefield. Empty fields are ignored. Theconventional meaningof each field isas follows: 



a Thenameof an author. If the name contai ns a titlesuch asjr. at the end, it should be separated from the 

last name by a comma. Therecan be multi pie occurrencesof the a field. The order issignificant. It isa 
good idea alwaysto supply an a field or ao field. 

b Foran articlethat is part of abook, thetitleof thebook. 

c The place (city) of publication. 

d Thedateof publication. Theyear should bespecified in full. Ifthemonth isspecified, the name rather 

than the number of themonth should beused, but only the first three I etters are requi red. It isa good idea 
alwaysto supply a d field; if the date isunknown, a valuesuch asin press or unknown can beused. 

e Foran articlethat is part of abook, thenameof an editor of thebook. W herethework haseditorsand no 

authors, thenamesof theeditors should begiven asA fields (ed) or (eds) should beappendedto the last 
author. 

g U .S. government ordering number. 

i The publisher (issuer). 

j Foran articlein ajournal, thenameof the journal. 

k Keywordsto beused for searching. 

l Label. 

n Journal issue number. 

o Other information. Thisisusually printed attheend of thereference. 

p Pagenumber. A rangeof pagescan bespecified asm-n. 

q Thenameof the author, if the author isnot a person. Thiswill only beused if thereareno a fields. There 

can only beoneo field. 
r Technical report number. 

s Seriesname. 

t Title. Foran articlein a book or journal, thisshould be the title of the article. 

v Volume number of thejournal or book. 

x Annotation. 



Forali fi el ds except a and e, if there is more than oneoccurrenceof a parti cui ar field in a record, only the last such field will 
beused. 

If accent stri ngs are used, they should follow thecharacter to beaccented. ThismeansthattheAM macro must beused with 
the -ms macros. Accent stri ngs should not be quoted: use one \ rather than two. 

CITATIONS 

T he format of acitation is 

. [openi ng- 1 ext 
flags keywords 
f i el ds 

-]cl osi ng-text 
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Theo peni n g - 1 e x t , ci osi ng-text , and f i ags components are optional. Only oneof thekeywords and f i e i d s components need 
bespecified. 

Thekeywords component says to search thebibliographic databasesfor a referencethat contai ns ali thewords in keyword s. It 
isan errar if morethan onereferenceif found. 

T he f i e i d s components specifies additi onal fieldsto replace or supplement those specified in the reference. When references 
are bei ng accumulated and thekeywords component isnonempty, then addi ti onal fields should bespecified only on the first 
occasion that a particular reference iscited, and will apply to ali citationsof that reference. 

Theopeni ng-text and ci osi ng-text component specifies strings to beused to bracket the label instead of the stri ngs speci fi ed 
in the bracket -label command. If either of these components is nonempty, the stri ngs specified in the bracket -label 
command will not beused; thisbehavior can bealtered usi ng the [ and ] flags. N otethat leadingand trailingspacesare 
significant for these components. 

Thef i ags component isa list of nonalphanumeric characters, each of which modifies the treatment of this particular 
citati on. UNIX reter will treat these flags as part of the keywords and so will ignorethem becausethey are 
nonalphanumeric. The following fi ags are currently recognized: 

# This says to use the label specified by the short -label command, instead of that specified by theiabei command. 

If no short label hasbeen specified, thenormal label will beused. Typically, theshort label is used with author- 
datelabelsand consistsof only thedate and possi bly a disambi guati ngletter; the# issupposedto be suggestive of 
anumerictype of label. 

[ Precede o peni ng-text with the first stri ng specified in the bracket -label command. 

1 Follow ci osi ng - text with thesecond st ring specified in the bracket -label command. 

Oneadvantageof usi ng the [ and ] flags rather than including the brackets in open i ng-text and ci osi ng-text isthatyou can 
changethestyleof bracket used in the document just by changing the bracket -label command. Another advantageisthat 
sorti ng and merging of citationswill not necessari ly beinhibited if the flags are used. 

If a label isto beinserted into the text, itwill beattached to the line precedi ng the . [ line. If thereisno such line, then an 
extra linewill beinserted beforethe.[ lineand awarningwill begiven. 

There isno special notation for making acitation to multiple references. J ust use a sequenceof citati ons, onefor each 
reference. Don't put anything between the citations. The labdsfor ali the citationswill beattached to the line precedi ng the 
fi rst citation. T he labels may also besorted ormerged. (Seethedescri ption ofthe<> label expression, and of thesort- 

adj acent- labels and abbreviate -label -ranges COITimand.) A label will not be merged if itS Citation hasa nonempty open i ng- 
text orci osi ng - text . H owever, the labels for acitation usi ng the ] flag and without any ci osi ng-text immediately followed 
by acitation usi ng the [ flag and without any o peni ng-text may besorted and merged even though the fi rst ci tati on 's 
openì ng - text or thesecond citation'sci osi ng-text is nonempty. (If you want to prevent this, just makethefirst citation's 

ci osi ng- text \ &.) 

COMMANDS 

Commands are contained between lines starting with .ri and .R2. Recognition of these li nes can beprevented bythe-R 
option. When an .ri line is recognized, any accumulated references are fi ush ed out. N either .ri nor .R2 lines, nor anything 
between them, is output. 

Commands are separated by newlinesor semicolons. # introducesacomment that extendsto the end of the line (but does 
not conceal thenewline). Each command is broken up into words. Words are separated by spaces or tabs. A word that begins 
with an open quote (") extendsto thenext dose quote (") that is not followed by another open quote ("). If thereisno such 
open quote (") the word extendsto the end of the li ne. Pairsof open quotes(") in a word beginningwith collapseto a single 
open quote ("). N either # nor ; is recognized inside open quotes("). A line can be conti nued by ending it with \; thisworks 
everywhere except after a #. 

Each command n a me that ismarked with * hasan associated negative command no-name thatundoestheeffectof name. For 
example, theno-sort command specifies that references should not besorted. The negative commands take no arguments. 
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abbreviate*f el ds stringi 
st r i n g 2 string3st r i n g 4 



In thefollowing descri ption, each argument must bea single word; f i e i d isused for asingleuppercaseor lowercaseletter 
naming afield; fi et d s isused for asequenceof such letters; m and n areused for a nonnegative numbers; stri ng isused for an 
arbitrary stri ng; fi i e n a me isused for thenameof a file. 

Abbreviate the first namesof f i e i d s . A n i n iti al letter will beseparated from another 
initial letter by stri ngi, from thelast nameby str ì n g 2 , and from anything else (such 
as avon orde) by st ri n g 3. These default to a peri od followed by a space. In a 
hyphenated first name, the initial of the first part of the name will beseparated from 
thehyphen by stri r g 4 ; thisdefaultsto a peri od. N 0 atterri pt ismadeto handleany 
ambiguities that might resultfrom abbrevi ation. N ames are abbrevi ated before 
sorting and beforelabel construction. 

T hree or more adjacent labels that refer to consecutive references wi II be abbrevi ated 
to a label consisti ngof the first label, followed by stri ng, followed by thelast label. 
Thisismainly useful with numeric labels. If stri ng isomitted itdefaultsto -. 
Accumulate references instead of writing out each referenceasit isencountered. 
Accumulated references will bewritten outwheneverareferenceoftheform: 



abbreviate-label-ranges*st r i ng 



accumulate* 



$LIST$ 



annotate*f i el dstring 



articlesst ring ... 
s t r i n g ... 

bibliograptiyf i I ename 
bracket-labelst r i ng 
lstring2st r i n g 3 

capitalizef i el ds 
compatible* 

databasef i I ename . . . 



date-as-label*st r i ng 



default-database* 



isencountered, after ali input fi leshavebeen processed, and whenever an .ri lineis 
recognized. 

f i ei d isan annotation; print it at the end of thereferenceasa paragraph preceded by 

theline 

.stri ng 

If macro isomitted, itwill default to Ap;if tieid isalso omitted, itwill default to x. 
Onlyonetieid can bean annotation. 

These are definiteor indefinite articles, and should beignored at the beginni ngof t 
fieldswhen sorting. Initially, the, a, and an are recognized as articles. 
Writeoutall the references contained in the bibliographic databasesf i ename ... 
In thetext, bracketeach label with stri ngi and stri n g 2 . An occurrenceof stri n g 2 
immediately followed by stri n g 1 will beturned into st ri n g 3. The default behavior is 
bracket-label \*([. \*{.] ", " 
C onvert fi e 1 d s to caps and smal I caps. 

Recognize .ri and .R2 even when followed by acharacter otherthan space or 
newline. 

Search the bibliographic databasesf i i ename .. . For each fi i ename if an index 

fi i ename .i created by gindxbib(l) exists, then itwill besearched instead; each index 

can cover multipledatabases. 

str i ng is a label expression that specifies a stri ng with which to replacethe d fidd 
after constructing the label. See "Label Expressions," later in thismanual page, fora 
descri ption of label expressions. Thiscommand is useful if you do notwant explicit 
labels in the referen ce list, but instead wantto handleany necessary disambiguation 
by qualifying the date in some way. The label used in thetext would typically be 
somecombination of theauthorand date. In mostcases, you should also use the no- 
ìabei-in-reterence command. Forexample, 
date-as-label D.+yD.y%a*D. -y 

would attach adisambiguating letter to theyear part of theD field in the referen ce. 
The default database should besearched. Thisis the default behavior, so the negative 
version of thiscommand ismore useful. refer determi neswhether the default 
database should besearched on the first occasion that it needsto do a search. Thus, a 
no-defauit-database command must begiven before then, in orderto beeffective 
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discard*f i e I d s 
et-al*st ri n g mn 

includef i I ena me 
join-authorsst ri n g 1 
string2st r i ng3 

label-in-reference* 
label-in-text* 

labelst r i ng 

separate- label -second-parts 

stri ng 

move-punctuation* 

reverse*st r i ng 

search-ignore*f i e I d s 
search-truncate*n 

short-label*st r i ng 

sort*st r i ng 

sort- ad j aceri t- labels* 



When thereferenceisread, fi e i d s should be discarded; no stri ng definitionsfor 
fi e i d s will be output. Initially, f i ei ds arexYz. 

Control use of et al in the evaluation of@ expressions in label expressions. If the 
number of authors needed to make the author sequence unam bi guous i s u and the 
total number of authors ist , then the last t - u authors will bereplaced by stri ng, 
provided thatt - u isnot lessthan mandt is not lessthan n. The default behavior is 

et -al " et al" 2 3. 

Includef i ename and interpret the contentsas commands. 
Thissayshow authors should bejoined together. When thereareexactly two 
authors, they will bejoined with stri ngi. When there are more than two authors, ali 
but the last two will bejoined with stri n g 2 , and the last two authors will bejoined 

with st ri n g 3 . If st ri ng3 ÌS Olili tted, it will default tO s t r i ng 1 ; if s t r i n g 2 i S al SO 

omitted, itwill also default to stri ngi. Forexample, 

join- authors " and " ", " ", and " 

will restore the default method for joi ni ng authors. 

When outputtingthereference, define the stri ng [Fto be the reference's label. This 

is the default behavior; so the negative versi on of thiscommand ismoreuseful. 

Foreach reference, output a label in the text. The label will beseparated fromthe 

surroundingtextasdescribed in the bracket -label command.Thisisthe default 

behavior; so the negati ve versi on of thiscommand ismoreuseful. 

stri ng isa label expression describinghowto label each reference. 

W h en m ergi n g two- part I abel s, separate th e seco n d part of th e secon d I abel f ro m th e 

first label with stri ng. Seethedescription of the <> label expression. 

In the text, moveany punctuation at the end of line past the label. It is usuai ly a 

good ideato give thiscommand unlessyou areusing superscri pted numbersas 

label s. 

Reverse thefieldswhosenames are in st ri ng. Each field namecan befollowed by a 
number that say show many such fi elds should bereversed. If no number isgiven for 
a field, ali such fieldswill bereversed. 

W hile searching for keys in databasesforwhich no index exists, ignorethecontents 
off i ei ds. Initially, fields xyz areignored. 

Only requirethefirstn charactersof keysto begiven. In effect.when searching fora 
given key, words in the database are truncated to the maximum of n and the length 
of thekey. Initially, n is 6. 

str i ng is a label expression that specifiesan alternative (usuai lyshorter) styleof label. 
Thisisused when the # flag isgiven in the citation. When using author-date style 
labels, the identity of theauthor or authors issometimes clear from the co n text, an d 
so it may bedesirableto omit the author or authors from the label. The short -label 
command will typically beused to specify a label contai ning just a date and possi bly 
a disambiguating letter. 

Sort references accordi ngto stri ng. References will automatically beaccumulated. 
stri ng should be a I ist of field names, eachfollowed by anumber, indicatinghow 
many fields with the name should beused for sorti ng. + can beused to indicate that 
ali thefields with the name should beused. Also, . can beused to indicate the 
references should besorted using the (tentati ve) label. (The "Label Expressions" 
su bsecti o n descri bes t h e co n cept of a tentati ve I abel . ) 

Sort labels that areadjacent in the text accordi ng to their position in the reference 

list. Thiscommand Should USUally begiven if theabbreviate-label-ranges 

command hasbeen given, or if the label expression containsa<> expression. This 
will have no effect unless references are bei ng accumulated. 



grefer 
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LABEL EXPRESSIONS 

Label expressi onscan beevaluated both normally and tentatively. The result of normal evaluation isusedfor output. The 
resultof tentati ve evaluation, called the tentati ve label, isused to gather the i nformation that normal evaluation needsto 
disambiguate the label. Label expressions specified by thedate-as-iabei and short-iabei commandsarenotevaluated 
tentatively. N ormai and tentati ve evaluation arethesamefor ali typesof expressi on other than e, *, and % expressions The 
following descri ption appliesto normal evaluation, exceptwhereotherwise specified. 

fieid, fieid n The nth part of field. If n isomitted, it defaults to 1. 
■stri n g ■ T he characters in s t r i ng I iterai ly. 

e Ali theauthorsjoined as specified by the join- authors command. Thewholeof each author'sname 

will beused. H owever, if thereferencesaresorted by author (that is the sort specification startswith 
A+),then authors' lastnameswill beused instead, provi ded that thisdoes not introduce ambiguity, and 
also an initial subsequenceof the authors may beused instead of ali theauthors, again provided that 
thisdoes not introduce ambiguity. The use of only the last nameforthei -th author of some reference 
isconsidered to beambiguousif there issomeother reference, such that the first i - 1 authorsofthe 
references are the same, the i-th authors are not the same, but the i-th authors' last names are the 
same. A proper initial subsequenceof the sequenceof authors for some reference isconsidered to be 
ambiguous if there is a reference with some other sequence of authors that also has that subsequence as 
a proper initial subsequence. W hen an initial subsequenceof authors isused, the remai ni ng authors are 
replaced by the stri ng specified by the et -ai command; this command may also specify additional 
requirementsthat must bemet beforean initial subsequence can beused. » tentatively evalu atesto a 
canonical representation of theauthors, such that authors that compare equallyfor sorti ng purposewill 
havethesame representati on. 

%n, %a, %a, %i, %i The seri al number of the reference formatted accordi ngto thecharacter following the %. The serial 

number of a reference is 1 plus the number of earlier references with same tentati ve label asthis 

reference. T heseexpressionstentatively evaluateto an empty string. 
e x p r * If there is another reference with the same tentati ve label asthis reference, then expr ; otherwise, an 

empty string. It tentatively evaluatesto an empty string. 
expr+n, expr-n The first (+) or last (-) n uppercaseor lowercase lettere or digitsof expr . troff special characters (such 

as\( 'a> count as a single letter. Accent stri ngs are retai ned but do not count toward the total, 
expr . i expr converted to lowercase. 

expr .u expr converted to uppercase. 

expr .c expr converted to caps and smal I caps. 

expr.r expr reversed so that the last name is first. 

expr. a expr with first names abbreviated. N otethat fields specified in the abbreviate command areabbrevi- 

ated beforeany labels are evaluated. Thus .a isuseful only when you want a field to be abbreviated in a 
label but not in a reference. 

expr . y Theyear part of expr . 

expr.+y T he part of ex pr before theyear, or the whole of ex pr if itdoes not contai n ayear. 

expr . -y T he part of ex pr after theyear, or an empty string if expr does not contain ayear. 

expr.n The last name part of expr . 

expriexpr2 expri except that if the last character of expr 1 is- then itwill be replaced by e x p r 2 . 

expri e x p r 2 T he concatenation of ex p r i and ex pr 2 . 

exprl|expr2 Ifexprl ÌS nonempty, then ex pr 1 ; Otherwise, expr 2 . 

expr i&expr2 Ifexprl is nonempty, then expr 2; otherwise, an empty string. 

expr l?expr2 : e x p r 3 Ifexprl ÌS nonempty, then ex pr 2 ; Otherwise, expr 3 . 

<expr > The label isin two parts, which areseparated by expr . Two adjacent two-part labels that havethesame 

first part will bemerged by appendi ng the second part of the second label onto the first label separated 
by the string specified in theseparate-iabei-second-parts command (initially, a commafollowed by a 
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space); the resulti ng label wi II al so bea two-part label with the same first part as bef o rem ergi ng, and so 
additional label scan bemerged into it. N otethat it is permissive for the first part to beempty; this 
may bedesirableforexpressionsused in the short -label command. 
(expr ) Thesameasexpr . U sed for grouping. 

The preceding expressions are listed in orderof precedence(highest first); & and \ have the same precedence 
MACRO INTERFACE 

Each referencestartswith a cali to themacro ] -. The stri ng [f wi 1 1 bedefined to be the label for this reference, unlesstheno- 
iabei-in-reference command hasbeen given. Therethen follows a seriesof stri ng definiti ons, one for each field: stri ng [X 
correspondsto field x. The number register [ p i s set to 1 if the p field contai ns a rangeof pages. The [t, [a, and [o number 
registers are set to 1 accordi ng astheT, a, and o fields end with oneof thecharacters .?!. The [e number register wi II beset 
to 1 if the [E string contai ns more than one name The reference isfollowed by a cali to the n macro. The first argument to 
thismacro gives a number representi ng the typeof the reference. If a reference contai ns a j fidd, it will beclassified astypel; 
otherwise if it contai nsa b fidd, itwill betype3; otherwise, if it contains a G orR fidd itwill betype4, otherwiseif it 
containsan i field, itwill betype2; otherwise, itwill betypeO. Thesecond argument isasymbolic name for the type other, 
journai-articie, book, articie-in-book, or tech - report. G roups of references that have been accumulated or are produced by 
the bibliography command arepreceded by a cali to the ]< macro and followed by a cali to the ]> macro. 

FILES 

/usr/dict/papers/md D efault database 
fi i e.i Index files 

SEEALSO 

gindxbìb(l), glookbib(l), lkbib(l) 

BUGS 

In label expressions, <> expressions are ignored inside, char expressions. 

G roff V ersi on 1.09 

grep, egrep, fgrep 

grep, egrep, fgrep— Print lines matching a pattern 
SYNOPSIS 

grep [ -[ [AB] ]num ] [-[CEFGVBchilnsvwx] ] [-e ] pattern j -f f i I e ] [ f i I e s . . . ] 

D ESC RIFIO N 

grep searches the named input fi i es (or standard input if no files are named, or the filmarne- is given) for lines containing a 
match to the given pattern. By default, grep prints the matching lines. 

T here are three major vari antsof grep, controlied by thefollowingoptions: 

-G I nterpret pattern as a basic regular expressi on (see the list following this one). This is the default. 
-e I nterpret pattern asan extended regular expression. 

-f I nterpret pattern asa list of fixed strings, separated by newlines, any of which isto bematched. 

In addition, two variant programs, egrep and fgrep, are available egrep issimilar (but not identical) to grepn-E, and is 

Compatì bl e with the hi Storical UNIX egrep. Fgrep ÌS the same aSgrepn-F. 

Ali variantsof grep understand thefollowingoptions: 
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-num M atches will beprinted with num linesof leading and trailing context. H owever, grep will never print 

any given line more than once. 
-a num Print num linesof trailing context after matching lines. 

-b num Print num linesof leading context before matching lines. 

-c Equivalentto -2. 

-v Print the versi on number of grep to standard error.This versi on number should beincluded in ali bug 

reports. 

-b Print the byte offset with in the input fi le before each lineof output. 

-c Suppress normal output; instead print a count of matchinglinesforeach input file. With the-v 

option, count nonmatching lines. 
-e pattern Usepattern asthe pattern; useful to protect patterns beginning with -. 

-ffiie Obtain the pattern from fi i e. 

-h Suppress the prefixing of fi lenameson output when multi pie fi les are searched. 

-i Ignore casedistinctions in both thepattem and the input files. 

-l Suppress normal output; instead print the nameof each input fi le from which no output would 

normally havebeen printed. 

-ì Suppress normal output; instead print the nameof each input filefrom which output would normally 

havebeen printed. 

-n P refi x each lineof output with theline number within itsinputfile 

-q Q uiet; suppress normal output. 

-s Suppress errar messages about nonexistent or unreadable files. 

-v Invert thesenseof matching, to select nonmatching lines. 

-w Select only those lines contai ni ng matchesthatform wholewords. The test isthat the matching 

substri ng must either be at the beginning of the line, or preceded by a nonword consti tuent character. 
Similarly, it must be either at the end of the li ne or followed by a nonword-constituent character. 
Word-constituentcharactersareletters, digits, and theunderscore. 

-x Select only those matches that exactly match the whole li ne. 



REGULAR EXPRESSIONS 

A regular expressi on is a pattern that descri bes a set of strings. Regular expressi ons are constructed analogously to arithmetic 
expressions, by using variousoperatorsto combinesmaller expressions. 

grep understands two different versi ons of regular expression syntax: basic and extended. In GN U\grep, there isno difference 
in available functionality using either syntax. In other implementati ons, basic regular expressions are less powerful. The 
following descri ption appliesto extended regular expressions; differencesfor basic regular expressions are summarized 
afterwards. 

Thefundamental building blocks are the regular expressionsthat match a single character. M ost characters, i ncludi ng al I 
letters and digits, are regular expressionsthat match themselves. Any meta character with special meaning may bequoted by 
preceding it with a backslash. 

A list of characters enclosed by [ and ] matches any single character in that list; if the first character of the list isthe caret (") 
then it matches any character not in the list. For example, the regular expression [0123456789] matches any single digit. A 
rangeof ASCII characters may bespecified by givi ng the first and last characters, separated by a hyphen. Finally, certain 
named classesof characters are predefi ned. Their names are self-explanatory, and they are[ :ainum: ], [: alpha: ], [: entri: ], 

[ : digit : ], [ :graph: ], [ :lower: ], [ : print : ], [ :punct : ], [ : space: ], [ : upper: ], and [ :xdigit : ] . For example, [ [ :alnum: ] ] 

means [o-9A-za- 1], exceptthelatter form isdependent upon the ASC II character encoding, whereastheformer isportable. 
(N otethat the brackets i n these class names are part of the symbolic names, and must beincluded in addi ti on to thebrackets 
delimiting the bracket list.) M ost meta characters lose their special meaning inside liste. To include a I iterai ], place it first in 
the list. Similarly, to include a li teral -, place it anywherebut first. Finally, to include a I iterai --, place it last. 

The peri od matches any single character. The symbol \w isasynonym for n :ainum: n and \w isasynonym for r[:ainum]]. 
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Thecaret and the dollar sign are meta charactersthat respectively match theempty stri ngat the beginning and end of a line. 
Thesymbols\< and \>, respectively, match theempty string at the beginning and end of a word. The symbol \b matchesthe 
empty string attheedgeof a word, and \b matchesthe empty string provi ded it'snot attheedgeof a word. 

A regular expression matching a single charactermay befollowed by oneof several repetition operators: 
? Thepreceding item isoptional and matched atmostonce. 

The precedi ng item wi II bematched zero or moretimes. 
+ Thepreceding item wi II bematched oneor moretimes. 

n Thepreceding item is matched exactly n times. 

n , Thepreceding item is matched n or moretimes. 
,m Thepreceding item isoptional and is matched at mostm times. 
n ,m Thepreceding item is matched at least n times, but not morethan m times. 

Two regular exp ressi onsmay beconcatenated; the resulti ng regular expression matchesany string formed by concatenati ng 
two substringsthat respectively match theconcatenated subexpressions. 

Two regular expressi onsmay bejoined by theinfixoperator |; the resulti ng regular expression matchesany string matching 
either subexpression. 

Repetition takesprecedenceover concatenation, which in turn takesprecedenceoveralternation. A whole subexpression may 
beenclosed in parenthesesto overridetheseprecedence rules. 

The back reference \n, wheren isa single digit, matchesthe substri ng previously matched by thenth parenthesized 
subexpression of the regular expression. 

In basic regular expressions, the meta characters |, (, and ) losetheir special meaning; instead usethebackslashed versions 
\?, \+, \f, \j, \(, and \). 

In egrep, the meta character { losesits special meaning; instead use\{. 
DIAGNOSTICS 

N ormally, exit status isa if matcheswerefound, and 1 if no matcheswerefound. (The .b -v option invertsthesenseof the 
exit status.) Exit status is 2 if there were syntax errarsi n the pattern, inaccessi ble input fi les, or other system errors. 

BUGS 

E-mail bug reportsto bug-gnu-utiis@prep.ai.mit.edu. Besureto include theword grep somewherein the"Subject:" field. 

Large repetition countsin the m , n construct may cause grep to use lots of memory. In addition, certain other obscure regular 
expressions requireexponential timeand space, and may cause grep to run out of memory. 

Back references arevery slow, and may requireexponential time. 

GNU Project, 10 September 1992 



grephistory 

grepnistory— D isplay filenamesfrom Usenet hi story fi le 
SYNOPSIS 

grephistory [ -f fi I e n a me ][-e ][-n ][-q ][-l ][-i ][-s ] [ me s s a g e i d ] 

D ESC RIFIO N 

grephistory queries the dbz(3) index into thehistory(5) filefor an article having a specified M essagelD . 

If messageid cannot befound in the database, the program prints "N ot found" and exitswith a nonzero status. If messageid is 
in the database, the program prints the pathname and exitssuccessfully. If no pattinarne exists, the program will print /dev/ 
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nuli and exit successfully. Thiscan happen when an article has been canceled, or if it has been expired but its history is stili 
retai ned. Thisis default behavior, which can beobtained by using the -n flag. 

If the -q flag isused, then no messageisdisplayed. The program wi II stili exitwith the appropriate exit status If the -e flag is 
used, then grephi story will only print thefilenameof an existing article. 

If the-i flag isused, then the enti re li ne from the history fi le will bedisplayed. 

If the-i flag isused, then grephi story will read a list of M essage-IDson standard input, oneper line Leadingand trailing 
whitespaceisignored, asareany malformed lines. Itwill print on standard output thoseM essage-IDsthat are not round in 
the history database. This flag isused in processing ihave control messages. 

If the-s flag isused, then grephi story will read a si mi lar list from its standard input. Itwill print on standard output a list of 
filenamesfor each article that is stili available. This flag isused in processing sendme control messages. 

To specify adifferent value for the history file and database, use the -t flag. 
HISTORY 

W ritten by Rich $alz (r-saizuuunet.uu.net) for InterN etN ews. 
SEEALSO 

dbz(3), history(5) 
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grodvi— C onvert grot f output to T eX dvi format 
SYNOPSIS 

grodvi [ -dv ][-wn ] [ — Fd i r ][files ... ] 

D ESC RIFIO N 

grodvi is a driver for groff that producesdvi format. N ormai ly, it should berun by groff-Tdvi. This will run gtrotf-Tdvi; it 
will also input the macros/usr/iib/groff/tmac/tmac. dvi; if the input isbeing preprocessed with geqn, itwill also input /usr/ 

lib/grof f /f ont/devdvi/eqnchar. 

The dvi fi le generated by grodvi can beprinted by any correctly written dvi driver. The troff drawing pri miti ves are 
implemented using the tpic version 2 speci als. If the driver does not support these, the \DCommands will not produce any 
output. 

Thereisan additional drawing command available 

\d ■ Rd h dv' D raw a rule (solid black rectangle), with one corner atthecurrent position, and thediagonally 

opposite corner atthecurrent position +(dh ,dv ). Afterwards, thecurrent position will beat the 
opposi te corner. This produces a rule in the dvi fi le and so can beprinted even with a driver that does 
not support the tpic specials, unliketheother \d commands. 

The groft command \x'anyt hi ng ■ istranslated into the same command in thedvifileaswould beproduced by \speciai{ 
anything } in TeX; ariyt hi ng may not contai n a newl ine. 

Font fi les for grodvi can becreated from tfm fi les using tfmtodit(l). The font descri ption fi le should contai n thefollowing 
additional commands: 

internalname name The name Of the tfm file (without the .tfm extension) iSname. 
checksum n The checksum in the tf m file ÌSn . 

designsize n The designsize in the tf m file ÌSn . 



T hese are automati cai ly generated by tf mtodit. 
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In troff, the \n escape sequencecan beused to access characters by their positi on in thecorrespondingtfm file; ali characters 
in thetfm filecan beaccessed thisway. 

OPTIONS 

-d Do notusetpic specialsto implement drawing commands. H orizontal and vertical lineswill beimplemented by 

rules. Other drawing commands will beignored. 
-v P ri nt the versi on number. 

-wn Set the default linethicknessto n thousandthsof an em. 

-Fd i r Search directory di r /devolvi forfont and devi ce descri ption files. 

FILES 

/usr/iib/groff/font/devdvi/DEsc D evi cedescri ption file 
/usr/iib/groff/font/devdvi/ f Font description file for font F 

/usr/lib/groff/tmac/tmac.dvi M acrosfor use Witti grodvi 

BUGS 

dvi filesproduced by grodvi use a different resolution (57,816 uni ts per inch) than those produced by TeX. Incorrectly 
written driversthat assume the resolution used by TeX, rather than using the resolution specified in the dvi file, will not 

WOrk with grodvi. 

When using the -d option with boxed tables, vertical and horizontal linescan sometimes protrudeby one pixel. Thisisa 
consequenceof thewayTeX requires that the heights and widthsof rules berounded. 

SEEALSO 

tfmtodit(l), groff(l), gtroff(l), geqn(l), grof f_out(5), groff_f ont(5), grof f_char(7) 

Groff Versi on 1.09 14 
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groff — Front end for the groff document formatti ng system 
SYNOPSIS 

groff [ -tpeszaivhblCENRVXZ] [-wname ][-Wname ][-mname ] [ — F d i r ][-Tdev ] [ -ffam ] [ — Md i r ] [ -de s ][-rcn ][-nnum ] 
[-ol i st ] [-Par g ][f il es ... ] 

DESCRIPTION 

groff is a front-end to the groff document formatti ng system. N ormally, it runsthegtroff program and a postprocessor 
appropriate for the selected device. Available devices are 

ps For PostScript printers and previ ewers 

dvi For TeX dvi format 

X75 For a 75 dpi Xll previewer 

X100 For a lOOdpi Xll previewer 

ascii For typewriter-like devices 

latini For typewri ter-l i ke devices usi ng the I SO Latin-1 character set. 

The postprocessor to beused for a device is specified by thepostpro command in the device descri ption file. Thiscan be 
overridden with the -x option. 

The default device isps. It can optional ly preprocesswith any of gpic, geqn, gtbi, grefer, orgsoeiim. 
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Optionswithout an argument can begrouped behind a single -. A filenameof - denotes the standard input. 
The grog command can be used to guess the correct groff command to use to format a file. 

OPTIONS 

Printahelpmessage. 

Preprocesswith geqn. 

Preprocesswith gtbi. 
Preprocesswith gpic. 
Preprocesswith gsoeiim. 

Preprocesswith grefer. N o mechanism isprovided for passing argumentsto grefer becausemost grefer options 
haveequivalent commandsthat can beincluded in thefile. Seegrefer(l) for more details. 
M ake programs run by groff print out their version number. 
Printthepipelineon stdout instead of executing it. 
Suppress output from gtroff.Only errar messageswill beprinted. 

Do not postprocess the output ofgtroff. N ormally, groff will automatically run the appropriate postprocessor. 
Passa rg to the postprocessor. Each argument should bepassed with a separate -p opti on. N otethat groff does not 
prepend - to a r g before passi ng it to the postprocessor. 

Send the output to a printer. The command used for this isspecified by the print command in the device 
description file. 

Passa rg to the spooler. Each argument should bepassed with a separate -l option. N otethat groff does not 
prepend - to a r g before passi ng it to the postprocessor. 
P repare output for devi ce t e v . T he default devi ce isps. 

Previ ew with gxditview instead of usi ng the usuai postprocessor. This isunlikely to produce good resultsexcept 

With -Tps. 

Don't allow newlineswith eqn delimiters. This is the sameas the -n option in geqn. 

-f f a m, and -nn u m are descri bed i n 



-h 
-e 
-t 
-P 
-s 
-R 



-V 
-z 
-Z 

-Pa r g 
-1 

-La r g 

-Tdev 
-X 



Theoptions -a, -b, -i 

gtroff(l). 

ENVIRO NMENT 

GROFF COMMAND PREFIX 



GROFF_TMAC_PATH 
GROFF_TYPESETTER 
GROFF_FONT_PATH 
PATH 

GROFF TMPDIR 



-C, -E, -wn a me , -Wn a me , -mn a me , -ol i s t , -de s , -re n , — Fd i r , -Md i r , 



If this ÌS Set X, then groff Will run Xtroff instead Ofgtroff. ThisalSO applies tO tbl, pie, eqn, refer, 
and soelim. It does not apply tO grops, grodvi, grotty, and gxditview. 

A colon-separated list of di rectories in which to search for macro files. 
Default device. 

A colon-separated list of di rectories in which to search forthedevname directory. 
The search path for commandsexecuted by groff. 

The directory in which temporary files will becreated. If this is not set and tmpdir i s set, temporary 
files will becreated in that directory. Otherwise, temporary files will becreated in /tmp. The 
grops(l) and grefer(l) commandscan create temporary files. 



FILES 



/usr/lib/groff /font/devname /DESC 

/ u srl I i b/ grof f/ f o n ti devn a me/ F 



Device description fi le for device name 
Font fi le for font F of device name. 



AUTHOR 

JamesClark (jjcejciark.com) 
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BUGS 

Report bugsto bug-groff@prep.ai.mit.edu. I nclude a complete, self-contained examplethatwill allow the bug to be 
reproduced, and say which version of groff you areusing. 

COPYRIGHT 

Copyright 1989, 1990, 1991, 1992 Free Software Foundation, Inc. 

groff isfree software you can redistri buteit or modify it under the termsof the G N U General Public Licenseas published 
by the Free Software Foundation; either version 2, or (atyour option) any later version. 

groff i s di stri buted in thehopethat itwill beuseful, butwithoutany warranty; withouteven theimplied warranty of 
merchantability or fitness for a particular purpose. SeetheGN U General Public Licensefor more details. 

You should havereceived a copy of theGN U General Public License along with groff; seethefile copying. If not, writeto 
the Free Software Foundation, 675 M assAve, Cambridge, MA 02139, USA. 

AVAILABILITY 

Themost recent released version of groff isalwaysavailableforanonymousftp from prep.ai.mit.edu (18.71.0.38) in the 
directory pub/gnu. 

SEEALSO 

grog(l), gtroff(l), gtbl(l), gpic(l), geqn(l), gsoelim(l), grefer(l), grops(l), grodvi(l), grotty(l), gxditview(l), 
groff_font(5), grof_out(5), groff_ms(7), groff_me(7), groff_char(7) 

Groff Version 1.09, 29 October 1992 

grog 

grog— Guess opti ons for groff com mand 
SYNOPSIS 

grog [ — o p t i on . . . ] [f i I es ... ] 

DESCRIPTION 

grog readsf i i es and guesses which of thegroff(l) options-e, -man, -me, -mm, -ms, -p, -s.and -t arerequired for printing 
fi i es, and prints the groff command includingthoseoptionson the standard output. A filenameof - istaken to referto the 
standard input. If no fi les are specified, the standard input wi II beread. Any specified optionswill beincluded in theprinted 
command. N o space i sali owed between opti ons and their arguments. Forexample, 

'grog -Tdvi paper.ms 

will guess the appropriate command to print paper.ms and then run it after addi ng the -Tdvi option. 
SEEALSO 

doctype(l), groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), gsoelim(l) 
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grops 

grops— PostScript driver for groff 
SYNOPSIS 

grops [ -glv ][-bn ][-cn ][-wn ] [ — Fd i r ] [fi les ... ] 



grops 




D ESC RIFIO N 

grops translates the output of GN U troff to PostScript. N ormally, grops should Peinvoked Py using thegroff command 
with a-Tps opti on. If no fi les are gi ven, grops will read the standard input. A filmarne of - will also cause grops to read the 
standard input. PostScript output iswritten to the standard output. When grops isrun by groff, optionscan Pepassed to 
grops by using thegroff -p option. 

OPTIONS 

-bn Workaround broken spoolersand previewers. N ormally grops produces output thatconforms the Document 

Structuring Conventionsversion 3.0. U nfortunately, some spoolersand previewers can't handlesuch output. The 
valueof n controis what grops doesto its output acceptableto such programs. A valueof 0 will cause grops not to 
employ any workarounds. Add 1 if no %%BeginDocumentsetup and %%EndDocumentsetup comments should be 
generated; thisisneeded for early versionsof TranScriptthat get confused by anything between the%%EndProiog 
comment and thefirst%%Page comment. Add 2 if lines in included filesbeginningwith %i should bestripped out; 
thisisneeded for Sun's pageview previewer. Add 4 if %%Page, %%Traiier, and %%EndProiog comments should be 
stripped out of included files; thisisneeded for spool ers that don't understand the%%BeginDocument and 
%%EndDocument comments. Add 8 if the first li ne of the PostScript output should be%!PS-Adobe-2.e ratherthan 
v. ps -Adobe -3.0; thisisneeded when using Sun's N ewsprint with a printer that requi res page reversai . The default 
valuecan bespecified by abrokenn command in theDEsc file Otherwise, the default value iso. 

-cn Print n copi esofeach page. 

-g G uess the page length. Thisgenerates PostScript code that guesses the page length. The guess will becorrect only 
if the imageable area isvertically centered on the page. T hi s option allowsyou to generate documents that can be 
printed both on letter (8.5x11) paper and on A4 paper without change 

-ì Print the document in landscape format. 

-Fd i r Search the directory di r /devname for font and device description files; name is the nameof the device, usually ps. 
-wn Linesshould bedrawn using a thickness of n thousandthsof an em. 
-v Print the versi on number. 

USAGE 

T h ere are styl escali ed r, i, b, and bi mounted at font positionsl to 4. Thefontsaregrouped into families a, bm, c, h, hn, n, 
p, and t having membersin each of thesestyles: 



AR 


AvantGarde-Book 


AI 


AvantGarde-BookOblique 


AB 


AvantGarde-Demi 


ABI 


AvantGarde-DemiO blique 


BMR 


Bookman-Light 


BMI 


Bookman-Lightl talic 


BMB 


Bookman-Demi 


BMBI 


Bookman-Demiltalic 


CR 


Courier 


CI 


Courier-0 blique 


CB 


Courier-Bold 


CBI 


Courier- Boi dO blique 


HR 


H elvetica 


HI 


Helvetica-0 blique 


HB 


H el veti ca-B old 


HBI 


H elvetica- Boi dO blique 


HNR 


H elvetica-N arrow 


HNI 


H elvetica-N arrow-0 blique 
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HNB 


H elvetica-N arrow-Bold 


HNBI 


H elvetica-N arrow-BoldO blique 


NR 


N ewCenturySchlbk-Roman 


NI 


N ewCenturySchlbk-ltalic 


NB 


N ewCenturySchlbk-Bold 


NBI 


NewCenturySchlbk-BoIdltalic 


PR 


Palatino-Roman 


PI 


Palatino-Italie 


PB 


Palatino-Bold 


PBI 


Palatino-Boldltalic 


TR 


Times-Roman 


TI 


Times-ltalic 


TB 


Times-Bold 


TBI 


Times-Boldltalic 



There isalso thefollowing font which isnot a member of afamily: 
zcmi ZapfChancery-M ediumltalic 

There are al so somespecial fontscalled ss and s. Zapf D i n gbats i s avai I abl e as zd and a reversed version of ZapfD ingbats 
(with symbols pointing in the opposi te direction) isavailableaszDR; most charactersin thesefontsareunnamed and must be 
accessed usi ng \n. 

grops understandsvariousx commands produced usi ng the \x escape sequence; grops will only interpret commands that 
begin with a ps: tag. 

\x'ps:execcode' T his executes the arbitrary PostScript commands in code. The PostScript currentpoint will be setto 

theposition of the\nx command beforeexecuting code. The origin will beat the top left corner of 
the page, and y coordinates will increasedown thepage.A procedure u will be defi ned that converts 
groff unitsto the coordi nate system in effect. For example 

\X ' ps : exec \nx u 0 rlineto stroke' 

will draw a horizontal lineoneinch long, code may makechangesto thegraphics state, butany 
changeswill persi st only to the end of the page. A dictionary containing the defi niti ons specified by 
det and mdef will beon top of the dictionary stack. If your code adds defi nitionsto this dictionary, 
you should allocate space for them using wpsmdef n \ Any defi ni tions will persi st only until the end 
of the page. If you use the \y escape sequence with an argument that namesa macro, code can 
extend over multiple li nes. For example, 

.nr x 1i 

.de y 

ps: exec 

\nx u 0 rlineto 

stroke 

\Yy 

isanotherway to draw a horizontal lineoneinch long. 

\x'ps:fi i ename' T his is the same as the exec command except that the PostScri pt code is read from file n a me . 

\x'ps:def code' Place a PostScri pt defi nition contai ned in code in theprologue. There should beat most one 

definition per \x command. Long definitionscan be split over several \x commands; ali the code 
argumentsaresimplyjoined together separated by newli nes. The defi ni ti ons are placed in a 
dictionary which isautomatically pushed on the dictionary stack when an exec command is 
executed. If you usethe\Y escape sequence with an argument that namesa macro, code can extend 
over multiple li nes. 
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\x ■ ps :mdef ne od e Likedef, except that code may contai n up to n defini ti ons. grops needsto know how many 

definitionscode contains so that it can create an appropri ately sized PostScript dictionary to contain 
them. 

\x'ps:importfiie Import a PostScript graphic from file. The argumentsiix, ìiy, urx, and ury givethePounding Pox 
ìixiiyurxurywidth of the graphic in the default PostScript coordinate system; they should ali Peintegers; ìix and ìiy 
[height] 1 are thex and y coordinate^ of the lower-left corner of the graphic; urx and ury are the x and y 

coordinatesof the upper-ri ght corner of the graphic; wi d t h and h e i ght are integers that givethe 
desired width and height in groff unitsof the graphic. The graphic wi 1 1 Pescaled so that it hasthis 
width and height and translated so that the lower-left corner of the graphic is located at the 
position associated with \x command. If the height argument isomitted, it will Pescaled uniformly 
in thex and y directionsso that it has the specified width. N ote that the contentsof the\x 
command are not interpreted bytroft; so verti cai space for the graphic is not automatically added, 
and thewidth and height argumentsarenot allowed to haveattached scaling indicators. If the 
PostScript fi le com pi ies with the AdoPeDocument Structuring Conventi ons and contains a 
%%BoundingBox comment, then thePounding Pox can Pe automatically extracted from within groff 
Py usingthesy requestto run thepsbb command. 
The-mps macros(which are automatically loaded when grops isrun Py the groff command) include a pspic macro that 
allowsa pictureto beeasily imported. Thishastheformat: 

.PSPIC file [ -L j -R j -I n ] [width [ height ]] 

file isthenameof the file contai ni ng the illustration; wi dt h and h e i ght givethe desired width and height of the graphic. The 
wi dth and h e i ght arguments may have scali ng indi cato rs attac h ed ; the default scaling indi cator ìsì. This macro will scale the 
graphic uniformly in thex and y directionsso that it isno morethan wi dth wideand hei ght high. By default, the graphic will 
Pehorizontally centered. The-L and -r cause the graphic to Peleft-aligned and right-aligned, respectively. The-i option 
causes the graphic to Peindented by n . 

\x'ps: invis 1 , \x'ps: endinvis 1 N o output wi II Pe generated for text and drawing commands that are Pracketed with 

these\X commands. These commands are intended for use when output from troff will 
bepreviewed Peforebeing processed with grops; if the previ ewer isunaPleto display 
certain characters or other construets, then other suPstitute characters or construets can 
beused for previ ewing Py Pracketingthem with these \x commands 

Forexample, gxditview isnot aPleto display a proper \(em character Pecause the standard X 11 fontsdo not provide it; this 
proPlem can PeovercomePy executing the following request: 

.char \(em \X'ps: invis'\ 

\Z' \v' -.25m' \h' .05m'\D'l .9m 0 1 \h 1 . 05m " \ 

\X'ps: endinvis 1 \ (em 

In thiscase, gxditview will PeunaPleto display the \ (em character and will draw theline, whereasgrops will pri nt the \ (em 
character and ignore theline. 

The input to grops must bein the format output by gtroff(l). Thisisdescribed in groff_out(l). In addition, the device and 
font descri ption fi Ies for the devi ce used must meet certain requirements. The devi ce and font descri ption fi Ies supplì ed for 
ps device meet ali these requirements. afmtodit(l) can beused to create font fi Ies from afm fi Ies. The resolution must bean 
integer multiple of 72 timesthesizescale. Theps device uses a resolution of 72000 and a sizescale of 1000. The devi ce 
description file should contain a command: 

paperlengthn 

which says that output should be generated that issuitablefor printingon a pagewhoselength is n machineunits. Each font 
description file must contain a command: 

internalnameps na me 



which says that the PostScri pt nameof the font ispsname. It may al so contain a command: 

encodingenc file 
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which saysthat the PostScri pt font should bereencoded using theencoding described in e n c _ f i i e; thisfileshould consistof a 
sequenceof linesof theform: 



wherepschar is the PostScript nameof thecharacter, and code is its position in theencoding expressed as a decimai integer. 
The code for each character given in the font fi le must correspond to the code for thecharacter in encoding file, orto the 
code in the default encoding for the font if the PostScript font isnot to be reencoded. Thiscodecan beused with the\N 
escape sequence i n troff to select thecharacter, even if thecharacter doesnot haveagroff name. Every character in the font 
fi le must exist in the PostScript font, and the widths given in the font file must match thewidthsused in the PostScript font, 
grops will assume that a character with agroff nameof space is blank (makes no markson the page); it can makeuseof such 
a character to generate more efficient and compact PostScript output. 

grops can automati cally include the downloadablefonts necessary to printthedocument. Any downloadablefonts which 
should, when required, beincluded by grops must belisted in thefile/usr/iib/groff/font/devps/downioad; thisshould 
consistof linesof theform: 



wheref ont is the PostScript nameof the font, and f i i e name is the nameof the file contai ni ng the font; lines beginningwith # 
and blank lines are ignored; fieldsmay beseparated by tabsor spaces; f i i ename will besearched for using the samemecha- 
nism that isused forgroff font metric fi les. The download file itself will also besearched for using this mechanism. 

If the fi le contai ni ng a downloadablefont or imported document conforms to the Adobe D ocument Structuring C onven- 
tions, then grops will interpret any comments in the fi les sufficiently to ensurethat itsown output is conformi ng. It will also 
supply any needed font resourcesthat are I isted in the download fileaswell asany needed fileresources. It is also ableto 
handleinterresourcedependencies. Forexample, suppose that you haveadownloadablefontcalled Garamond, and also a 
downloadablefont called Garamond-Outl ine that dependson Garamond (typically, itwould bedefined to copy Garamond's 
font dictionary, and changethePaintType), then it is necessary for Garamond to appear beforeGaramond-Outlinein the 
PostScript document. grops will handle thisautomatically provided that the downloadablefont fi le for Garamond-Outli ne 
indicete itsdependenceon Garamond by meansof the Document Structuring Conventions, for exampleby beginningwith 
thefollowing lines: 

%! PS-Adobe -3. 0 Resource-Font 
%%DocumentNeededResources : font Garamond 
%%EndComments 

%%IncludeResource: font Garamond 

In thiscase, both Garamond and Garamond-Outlinewould need to belisted in thedownload file. A downloadablefont 
should not include itsown name in a%%DocumentsuppiiedResources comment. 

grops will not interpret %%DocumentFonts commenta 

The%%DocumentNeededResources, %%DocumentSuppliedResources, %%IncludeResource, %%BeginResource, and %%EndResource 
COmmentS (or pOSSibly the Old %%DocumentNeededFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%BeginFont, and %%EndFont 

comments) should beused. 



pschar code 



font fi I e n a me 



FI LES 



/usr/lib/grof f /tmac/tmac . psnew 
/tmp/gropsXXXXXX 



/usr/lib/groff /tmac/tmac . ps 
/usr/lib/grof fi tmac/tmac. pspìc 
/usr/lib/grof f / tmac/tmac. psold 



/usr/lib/groff /font /de vps/DESC 
/usr/lib/groff /font /de vps/F 
/usr/lib/groff /font /de vps /download 
/usr/lib/groff /font /de vps/text . enc 



D evi cedescri ption file 
Font description file for font F 
List of downloadablefonts. 
E ncoding used for text fonts 

M acros for use with grops; automatically loaded by troff re 

Definition of pspic macro, automatically loaded bytmac.ps 

M acrosto disable use of characters not present in older PostScript printers; 

automatically loaded bytmac.ps 

M acrosto undo the effect of tmac.psoid 

Temporary file 
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SEEALSO 

afmtodit(l), groff(l), gtroff(l), psbb(l), grof f_out(5), groff_font(5), grof f_char(7) 

G roff Version 1.09, 14 February 1995 

grotty 

grotty— grof f driver for typewriter-li ke devices 
SYNOPSIS 

grotty [ -hfbuodBUv ][-Fdir ][files ... ] 

DESCRIPTION 

grotty translates the output of GN U troff into aform suitable for typewriter-li ke devices. N ormally, grotty should invoked 
by usi ng the grof f command with a -Tascii or -natim option. If no files are given, grotty wi II read the standard input. A 
filenameof - will also causegrotty to read thestandard input. Output iswritten to the standard output. 

N ormally, grotty printsa bold character cusingthesequence c backspace c' and an italic characterc by the sequ enee 
'_backspace c' . T hese sequences can bedisplayed on a terminal by piping through ui(l). Pagerssuch asmore(l) or iess(l) 
are also ableto display these sequences. U seeither -b or-u when piping into iess(l); use-b when piping into more(l). There 
isno need to filter the output through coi(l) si nce grotty never outputs reverse li ne feeds. 

T he font descri ption file may contai n a command: 

internalnamen 

wheren is a decimai integer. If the 01 bit in n is set, then thefontwill betreated asan italic font; if the 02 bit is set, then it 
will betreated asa bold font. The code fi eld in the font descri ption field gives the code that will beused to output the 
character. Thiscodecan also beused in the\N escape sequence in troff. 

0PTI0NS 

-Fdi r Search the directory di r /devname for font and device descri ption files; n a me is the nameof the device, usually ascii 

Or latini. 

-b Usehorizontal tabs in the output. Tabsareassumed to beset every 8 columns. 

-f Useform feeds in the output. A form feed will be output at the end of each page that hasno output on its last 
line. 

-b Suppress the use of overstriking for bold characters. 

- u Suppress the use of underl i n i ng for i tal i c characters. 

-b U se only overstriking for bold-italic characters. 

-u U se only underl ini ng for bold-italic characters. 

-o Suppress overstriking (other than for bold or underlined characters). 

-d I gnore ali \D commands. W ithoutthis, grotty will render \D'i commands that haveat least one zero 

argument (and so areeither horizontal or verti cai) using-, |, and + characters. 
-v P ri nt the version number. 

FILES 

/usr/iib/groff /f ont/devascii/DEsc D evi ce descri ption fi le for ascii device, 

/usr/iib/groff /f ont/devascii/F Font description file for font f of ascii device 

/usr/iib/groff /f ont/deviatini /desc D evi ce descri ption fi le for latini device, 

/usr/iib/groff /font/deviatim /f Font description filefor font f of latini device. 

/usr/iib/groff /tmac/tmac.tty M acrosfor use with grotty. 

/usr/iib/groff/tmac/tmac.tty-char Additional kludgy character defi nitions for use with grotty. 
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BUGS 

grotty isintended onlyforsimpledocuments. 

T here is no support for fractional horizontal orvertical motions. 

Thereisno support for \d commands otherthan horizontal and vertical lines. 

Charactersabove the first line {that is, with averti cai position of 0) cannot beprinted. 

SEEALSO 

groff(l), gtroff(l), groff_out(5), groff_font(5), groff_char(7), ul(l), more(l), less(l) 

Groff Versori 1.09, 14 February 1995 

gsoelim 

gsoeiim— Interpret .so requestsin groff input 
SYNOPSIS 

gsoelim [ -Cv ] [f i I es ... ] 

D ESC RIFIO N 

gsoeiim readsf 1 es and replaces lines of the form 

. sof ile 

by thecontentsof f i 1 e. It isuseful if filesincluded with so need to bepreprocessed. N ormally, gsoeiim should beinvoked 

with the-s option Of groff. 

OPTIONS 

-c Recognize .so even when followed by a character otherthan space or newl ine 
-v Printtheversion number 

SEEALSO 

groff(l) 

Groff Versioni. 09, 15 September 1992 

gtbl 

gtbi— Format tables for troff 
SYNOPSIS 

gtbl [ -Cv ][fi I es ... ] 

DESCRIPTION 

Thismanual page describes the GN U version oftbi, which ispart of the groff document formatti ng system, tbi compiles 
descriptionsof tables embedded within troff input fi lesinto commands that areunderstood by troff. N ormally, it should 
beinvoked using the-t option of groff. It ishighly compati ble with UNIX tbi. The output generated by GN U tbi cannot 
beprocessed with U N IX troff; it must beprocessed with GNU troff. If no filesaregiven on thecommand line, the 
standard input wi II beread. A filenameof - will cause the standard inputto beread. 
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OPTIONS 

-c Recognize .ts and .te even when followed by acharacter otherthan space or newline 
-v Print the version number 

USAGE 

Only thedifferences between GNU tbi and U N IX tbi aredescribed here 

N ormally, tbi attemptsto preventundesirablebreaks in thetableby usi ng diversione Thiscan sometimesinteract badly 
with macro packages' own useof diversions, when footnotes, for example, areused. Thenokeep option tei Is tbi not to try to 
prevent breaks in thisway. 

Thedecimaipoint option specifi es the character to berecognized as the deci mal pointcharacter in place of the default period. 
It takesan argument in parentheses, which must bea single character, asfor thetab option. 

Thet format modifier can be followed by an arbitrary length font namein parentheses. 

There is a d format modifier that meansthat averti cally spanning entry should bealigned at thebottom of its range. 

Thereisno limit on the number of columns in atable, nor any limiton the number of text blocks. Ali thelinesof atableare 
considered in decidi ngcolumn widths, not just the first 200. Table conti nuation (.t&) linesarenot restri cted to the first 200 
lines. 

N umeric and alphabetic items may appear in thesamecolumn. 
N umeric and alphabetic items may span horizontally. 

tbi uses register, string, macro and diversion names beginning with 3. When usi ng tbi, you should avoid using any names 
beginningwith a 3. 

BUGS 

You should use .tsh/.th in conjunction with asupporting macro package for ali multi page boxed tables. If there isno header 
that you want to appear at the top of each page of the table, place the .th lineimmediately after the format section. Do not 
enclose a multi page table within keep/releasemacros, or divert it in any otherway. 

A text block within a table must be ableto fit on onepage. 

The bp request cannot beused to force a page- break in a multi page table. Instead, defineBP asfollows: 

.de BP 

.ie '\\n(.z" .bp \\$1 
.el \!.BP \\$1 

and useBP instead of bp. 
SEEALSO 

groff(l), gtroff(l) 

Groff Version 1.09, 1 Aprii 1993 
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gtroff— Format documents 
SYN0PSIS 



gtroff [-abivzCER] [-wname] [-Wname] [-d cs] [ -f f a m] [-mname] [-n num] [ — o list] [-r cn] [-Tname] [ — F dir] [-M 
dir] [nf i I es. . . n] 
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D ESC RIFIO N 

Thismanual page describes the GN U version of troff, which ispart of thegroff document formatti ng system. It ishighly 
compati blewith U N IX troff. U sually, it should beinvoked usi ng thegroff command, which wi II also run p repro cesso rs and 
postprocessors in the appropri ateorder and with the appropriate options. 



OPTIONS 

-a Generatean ASCII approximation ofthetypeset output. 

-b Print a backtracewith each warning or errar message Thisbacktrace should help track down the cause of 

theerror. The line numbers given in the backtrace may not always correct: troff 's idea of line numbers 
gets confused by as or am requests. 

-i Read the standard input after ali the named input files have been processed. 

-v Print the version number. 

-wname E nable warning n a me . A vai lablewarni ngs are described in the "W arni ngs" subsection asfollows. M ulti pie 

-w options are allowed. 
-wn a me I n h i bi t warn i ng n a me . M u Iti pie -w opti ons are al I owed. 

-e Inhibit ali errar messages. 

-z Suppressformatted output, 

-c E nable com pati bi li ty mode. 

-dcs, -dname=s D efinec or na me to be a string s ; c must bea one-letter name. 
-ff am Use fan as the default font fami ly. 

-mname Read in the fi le tmac . ri a me . N Ormally, thiswill besearched for in /usr/lib/groff/tmac. 

-R Don't load troff re. 

-nnum N umber thefirst pagenum. 

-oi i st Output only pagesin list, which isacomma-separated list of page ranges; n means print pagen, m-n 

means print every pagebetween m and n, -n means print every pageup to n, n- means print every page 
from n. Troff will exit after pri nting the last pagein the I i st. 

-rcn, -rname=n Set number regi ster c ornarne to n; c must beaone-character name; n can beany troff numeri c expressi on. 

-m a me P repare output f o r devi ce n a me , rath er th an th e def au It ps. 

-Fd i r Searchdir for subdirectories devila me (name is the name of the device) for the desc file and font files before 

thenormal /usr/lib/groff/font. 

-Md i r Search directory di r for macro files before thenormal /usr/iib/groff/tmac. 

USAGE 



Onlythefeaturesnotin UNIX troff are described here. 
LONG NAMES 

Thenamesof number regi sters, fonts, strings/macros/diversions, special characters can beof any length. In escape 
sequences, whereyou can use (xx for atwo-character name, you can use [xxx] for a nameof arbitrary length: 



\[xxx] Print the speci al character called xxx. 

\f [xxx ] Setfontxxx. 

\*[xxx] Interpolatestringxxx. 

\n[xxx ] Interpolate number register xxx . 



FRACTIO N AL PO INT SIZES 

A scaled point isequal to 1/sizescale points, where sizescale is specified in the desc file (1 by default.) T here is a new scale 
indicator z that hastheeffect of multiplying by sizescale. Requestsand escape sequences in troff interpret argumentsthat 
representa point sizeas being in unitsof scaled points, but they evaluateeach such argument usi ng a default scale indicator 
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of z. Argumentstreated in thisway aretheargument to theps request, thethird argument to thecs request, thesecond and 
fourth argumentsto thetkf request, the argument to the\H escape sequence, and thosevariantsof the\s escape sequence 
that takea numeric expression astheir argument. 

Forexample, suppose sizescaleis 1,000; then ascaled pointwill beequivalentto amillipoint; the request .ps 10.25 is 
equivalent to .ps 10.25Z, and so setsthepoint sizeto 10,250 scaled points, which isequal to 10.25 points. 

Thenumber register \n(.s returns the point size in points as decimai fraction.Thereisalso a new number register \n[.ps] 
that returns the point size in scaled points. 

It would makeno senseto use the z scale indicator in a numeric expression whose default scale indicator wasneither u nor z, 
and so troff disallowsthis. Similarly, it would makeno senseto use a scali ng indicator otherthan z or u in a numeric 
expression whose default scaleindicatorwasz, and so troff disallowsthisaswdl. 

There isalso new scale indicator s that multi pi iesby thenumber of units in ascaled point. So, forexample, \n[ .ps]s isequal 
to im. Besurenotto confuse the s and z scale indicators. 

NUMERIC EXPRESSION S 

Spacesarepermitted in a number expression within parentheses. 
m i ndicates a scale of hundredths of an em. 
e 1 >?e 2 Themaximum of ei ande2. 

e 1 <?e 2 Theminimum of ei ande2. 

(c;e) Evaluatee usingc as the default scaling indicator. Ifc is missing, ignore scaling indicators in theevaluation 

of e. 

NEW ESCAPE SEQUENCES 

\ a ■ a n y t h i ng 1 This expandsto 1 ore accordi ng to whether anyt hi ng isor isnot acceptableasthenameof astring, 

macro, diversion, number register, environment, or font. Itwill return 0 i f anyt hi ng isempty.This 
isuseful if you wantto look up user input in some sortof associati ve table 

\cxxk 1 Typeset character named xxx. N ormally it ismoreconvenientto use \[xxx]. But \c hasthe 

advantagethat it is compati blewith recent versi onsofU N IX and isavailablein compati bility 
mode. 

\e This is equivalent to an escape character, but it'snot interpreted in copy mode. For example, 

stringsto start and end superscripting could bedefined likethis: 

.ds { W'-.Sims^Enl.speu/ieu 1 
.ds { \s0\v 1 .3m' 

The use of \e ensures that these definitionswill work even if \*t gets interpreted in copy-mode (for example, by bei ng used 
in a macro argument). 

\N'n' Typeset the character with coden in the current font, n can beany integer. M ost devicesonly have 

characterswith codesbetween 0 and 255. If the current font doesnot contai n a character with that 
code, special fontswill not besearched. The \n escape sequence can be conveniente used on 
conjunction with the char request: 

.char \[phone] \f(ZDnN'37' 

The code of each character isgiven in the fourth column in the font descri ption fi le after the 
charset command. It is possi bleto includeunnamed characters in the font descri ption fileby usi ng 
a nameof -; the \n escape sequence is the onlywayto use these. 

\R ' n 3 me n' This has thesame effect as . nrna me n 

\s(nn Set the point size to nn pointsinn must beexactly two digits. 

\s[n ], \s'n 1 Set the point sizeto n scaled points; n is a numeric expression with a default scale indicator ofz. 

\vx\ v(xx \ v[xxx ] I nterpolate the contentsof the environment variable xxx, asreturned by getenv(3). \v is interpreted 
in copy-mode. 
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\yx\y(xx \ Y[xxx ] Thisisapproximately equivalentto \x\*[xxx ] '. H owa/er, the contents of the stri ng or macro xxx 
arenot interpreted; also, it is permitted for xxx to havebeen defined as a macro and thus contai n 
newlines (it isnot permitted fortheargumentto \x to contai n newlines). The inclusi on of newlines 
requiresan extensionto theUNIX troff output format and wi II confuse driversthat do not know 
about thisextension. 

\z ■ a n y t hi ng 1 Print anything and then restorethe horizontal and vertical position; a n y t hi ng may not contai n tabs 

or leaders. 

\$a Thenameby which thecurrent macro wasinvoked. Theais request can makea macro havemore 

than onename 

\$* Ina macro, theconcatenation of ali theargumentsseparated by spaces. 

\$e Ina macro, theconcatenation of ali theargumentswith each surrounded by doublé quotes, and 

separated by spaces. 

\$( nn,\$[ n n n ] I n a macro, this gives the nn th or nnn th argument. M acros can have an unlimited number of 
arguments. 

\?anythi n g \ ? When used in a di versi on, this wi II transparently em bed anything in the di version. anyt h ng isread 

in copy mode. W hen the di version isreread, anything wi 1 1 be interpreted. anything may not contai n 
newlines; use \! if you wantto embed newlines in a di version. The escape sequence\? is also 
recognized in copy mode and turned into a single internai code it is this code that termi nates 

anything. ThUS 
.nr x 1 
.nf 
.di d 

\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 
.di 

.nr x 2 
.di e 
.d 
.di 

.nr x 3 
.di f 
.e 
.di 

.nr x 4 
.f 

will print 4. 

\/ This increasesthewidth of the precedi ng character so that the spaci ng between that character and 

thefollowing character will be correct if thefollowing character is a Roman character. For example, 
if an italicf isimmediately followed by a Roman right parenthesis, then in many fontsthetop right 
portion ofthefwill overlap the top left of the right parenthesis, producingf), which isugly. 
Inserti ng w produce and avoidsthisproblem. It isa good ideato use this escape sequence 
whenever an italic character is immediately followed by a Roman character without any intervening 
space. 

\, T his modifies the spacing of thefollowing character so that the spacing between that character and 

the preceding character will correct if the preceding character isa Roman character. For example, 
inserting \, between the parenthesis and thef changesto (f. It isagood ideato usethisescape 
sequence whenever a Roman character is immediately followed by an italic character without any 
intervening space. 

\) Like \&except that it behaves like a character declared with thecfiags request to betransparent for 

the purposes of end-of-sentence recognition. 
\' Thisproducesan unbreakable space that stretches like a normal interword space when a lineis 

adjusted. 

\# Everything up to and includi ng thenext newlineis ignored. This is interpreted in copy mode. This 

is like \% except that \% does not ignore the termi nati ng newline. 



NEW REQUESTS 

.alnxx yy 
.alsxx yy 



.asciifyxx 
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Create an aliasxx for number regi ster object named yy. Thenew nameand the old namewill be 
exactly equivalent. Ifyy isundefined, awarningof typereg will begenerated, and the request will 
be ignored. 

Create an aliasxx for request, string, macro, or diversion object named yy. Thenew nameand the 
old namewill be exactly equivalent (it issimilarto a hard rather than a soft link). Ifyy isunde- 
fined, a warningof typemac will begenerated, and the request will be ignored. The de, am, di, da, 
ds, and as requestsonly create a new object if the nameof the macro, diversion, or string diversion 
iscurrently undefined or if it is defi ned to bea request; normally, they modify thevalueof an 
exi sting object. 

This request only existsin order to makeit possi bleto makecertain grosshackswork with GNU 
troff. It unformats the diversion xx in such awaythat ASCII charactersthat wereformatted and 
diverted into xx will betreated likeordinary input characterswhen xx isreread. For example, this: 

.tr @. 

.di x 
9nr\n\1 
.br 
.di 

.tr @@ 
.asciify x 



.backtrace 
.break 

.cflagsndc2. 
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32 



. charc st ring 



will set register n to 1. 

Print a backtrace of the i nput stack on stderr. 

Break out of awhiie loop. Seealso thewhiie and continue requests. Besure notto confuse this with 
the br request. 

Charactersci , a, ... havepropertiesdetermined by n, which isoRed from thefollowing. 
Thecharacterendssentences. (Initially, characters . ? ! have this property.) 
Linescan bebroken beforethecharacter (initially, no characters have this property); a li ne will not 
be broken at a character with this property unless the characters on each side both have nonzero 
hyphenation codes. 

Linescan bebroken after the character (initially, characters - \(hy\(em have this property); a line 
will not bebroken at a character with this property unless the characters on each si de both have 
nonzero hyphenation codes. 

Thecharacter overl aps horizontal ly (initially, characters \(ui\(rn\(ru have this property). 
T h e eh aracter overl aps verti cai ly ( i n i t i al ly, eh aracter \ (br hasthis prò perty) . 
An end-of-sentence character followed by any number of characters with this property will be 
treated as the end of a sentenceif followed by a newlineortwo spaces; in other words, thecharacter 
is transparent for the purposes of end-of-sentence recogniti on; this is the same as havi ng a zero 
space factor in TeX (initially, characters ')]*\(dg\(rq have this property). 
Defi ne character c to be stri ng. Every time character c needsto beprinted, string will beprocessed 
in atemporaryenvironmentand the result will bewrapped up into a single object. Compatibility 
mode will beturned off and the escape character will be setto \ whilestr i ng isbeing processed. 
Any emboldening, Constant spaci ng, or track kerning will beapplied to this object rather than to 
individuai characters in stri n g . A character defi ned by this request can beused just likea normal 
character provided by the output device. I n particular, other characters can betranslated to it with 
thetr request; it can bemade the leader character by theic request; repeated patternscan bedrawn 
with thecharacter by usingtheu and \l escape sequences; words contai ning the character can be 
hyphenated correctly, if the hcode request isused to gi ve the eh aracter a hyphenation code. Thereis 
a speci al antirecursion feature U se of character with in the character's definition will behandled 
li ke normal characters not defi ned with char. A character definition can beremoved with the rchar 
request. 
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.chopxx 

.closest r e a m 

.continue 
.cpn 

.doxxx 
.famxx 

.fspecialf s1s2 
.ftrfg 



.hcodec1codelc2code2. 



. hlal ang 



.hlmn 



.hpff i I e 



. hymn 



. hysn 



. kernn 
.msof i I e 



. nrof f 



.openst r e a mf i I ena me 



Chop thelast character off macro, stri ng, or diversion xx . This is useful for removing thenewline 
from the end of diversi onsthat areto beinterpolated asstrings. 

Closethestream named stream; s t r e a m wi 1 1 no longer bean acceptable argument to thewrite 
request. Seethe open request. 

Finish thecurrent iteration of awniie loop. Seealso thewhiie and break requests. 

If n is nonzero or missing, enable compati bility mode; otherwise, disable it. In compati bility mode, 

long namesarenot recognized, and theincompatibilitiescaused by long namesdo not arise. 

Interpret. xxx with compatibility modedisabled. Forexample, .do tam t would havethesame 

effect as .tam t except that it would work even if compatibility modehad been enabled. N otethat 

the previous compati bility modeisrestored beforeany files sourced by xxx areinterpreted. 

Set the current font fami ly to x x . T he current font fami ly is part of the current envi ronment. See 

thedescription of thesty request for moreinformation on font families. 

When the current font isf , fontssi , s2 , .. . will be special; that is, they wi II searched for 

characters not in the current font. Any fontsspecified in thespeciai request will be searched after 

fontsspecified in thetspeciai request. 

T ranslate font f to g. Whenever a font named f is referred to in \f escape sequence, or in theft, 
ui, bd, cs, tkf, special, f special, tp, or sty requests, font g will beused. If g is missing, or equal to 
f , then font f will not betranslated. 

Set thehyphenation codeof character ci to co dei and that of c 2 to code 2 . A hyphenation code must 

bea single input character (not a special character) other than a digit or a space. I n i ti al ly, each 

lowercaseletter has a hyphenation code, which isitself, and each uppercaseletter has a hyphenation 

codewhich is the lowercase versi on of itself. Seealso thehpf request. 

Set thecurrent hyphenation languageto i ang. H yphenation exceptionsspecified with thet™ 

request and hyphenation patterns specified with thehpf request are both associated with the 

current hyphenation language. T he hia request is usually i nvoked by the trot t re file. 

Set the maximum number of consecutive hyphenated linesto n. If n is negative, thereis no 

maximum. T he default value is -1 . T his value is associated with thecurrent envi ronment. 0 nly 

li nes output from an environment counttowards the maximum associated with that envi ronment. 

Hyphens resulti ng from \% arecounted; explicit hyphens are not. 

Read hyphenation patterns from f i i e; this will be searched for in thesameway thattmac.name is 
searched for when the -mn a me option is specified. It should havethesame format as the argument to 
the\patterns primitive in TeX; the letters appearing in this fi le areinterpreted as hyphenation 
codes. A % character in the patterns fi lei ntroduces a comment that conti nuesto the end of the line. 
Thesetof hyphenation patterns is associated with thecurrent language set by thema request. The 
hpt request is usually i nvoked bythetroffrefile 

Set the hyphenat i on margin to n : when thecurrent adjustment mode is not b, the li ne will not be 
hyphenated if the line is no more than n short. The default hyphenation margin i sa. The default 
scali ng indicator for this request ism. Thehyphenation margin is associated with thecurrent 
environment. Thecurrent hyphenation margin isavailablein the \n[ .nym] register. 
Set the hyphenat i on spaceto n : when the current adjustment modeis b, don't hyphenatethelineif 
the line can bejustified by adding no more than n extra spaceto each word space. The default 
hyphenation space iso. The default scali ng indicator for this request ism. Thehyphenation space is 
associated with thecurrent environment. Thecurrent hyphenation space isavailablein the 
\n[ .hys] register. 

If n is nonzero or missing, enable pai rwisekerning; otherwise, disable it. 
Thesameastheso request except that f i e is searched for in thesameway that tmac.n a me is 
searched for when the-mname option i s specified. 

M akethen built-in condition trueand thet built-in condition false. Thiscan bereversed using 
thetroff request. 

Open f m ename for writing and associate the stream named stream with it. Seealso the dose and 
write requests. 




Like open, but if f i i e n a me exists, append to it instead of truncating it. 

Print thenamesand contentsof ali currently defined number regi sters on stderr. 

This behaves like the so request except that input comesfrom the standard output of c o mira n t . 

Print thenamesand positi onsof ali traps (not includi ng input linetrapsand diversion traps) on 

stderr. E m pty si ots i n the page trap list are printed aswell, becausethey can affect the priority of 

subsequently planted traps. 

Remove thedefinitions of charactersci , c2 , ... Thisundoestheeffectof a char request. 
Right justify thenext n input lines. Without an argument, right justify the next input line. The 
number of lines to be right justified isavailablein the \ n[.rj] register. This implicitly does .ceo. 
The ce request implicitly does .rje. 
Renarne number register xx toyy. 

Set the soft hyphen characterto c. If c isomitted, the soft hyphen character will be setto the 
default \(hy. The soft hyphen character is the character that will beinserted when a word is 
hyphenated at a line break. If the soft hyphen character does not exist in the font of the character 
immediately precedi ng a potential break point, then the li ne will not bebroken at that point. 
N either definiti ons (specified with the char request) nor translations (specified with the tr request) 
areconsidered when fi nding the soft hyphen character. 

In a macro, shiftthearguments by n positions: argument i beco mes argument i -n; argumentsi to n 
will no longer beavailable. If n ismissing, argumentswill be shifted by 1. Shifting by negative 
amountsis currently undefined. 

Fontssi, s2 are speci al and will besearched for characters not in the current font. 
Associate stylef with font posi ti on n. A font posi ti on can beassociated either with a font or with a 
style. The current font is the index of a font positi on and so isalso either a font ora style. When it 
isastyle, thefontthat isactually used i s the font the nameof which is the concatenati on of the 
nameof the current fami ly and the nameof the current style. Forexample, if the current font isi 
and font position 1 is associated with style r and the current font family is t, then font tr will be 
used. If the current font is not a style, then the current family isignored. When therequestscs, bd, 
tkf, ut, or f special are applied to a style, then they will instead beapplied to themember of the 
current family correspondingto that style. The default family can be set with the-t option.The 
styies command in theDEsc filecontrolswhich font positions (if any) are i ni ti ally associated with 
styles rather than fonts. 

Enabletrack kerningfor font f . When the current font is f , thewidth of every character will be 
increased by an amount between ni and n2; when the current point sizeisless than orequal to si, 
thewidth will be increased by ni; when it isgreaterthan or equal to s 2, thewidth will be increased 
by n 2 ; when the poi ntsize isgreaterthan orequal to si and lessthan orequal to s 2 , theincreasein 
width isalinearfunction of the poi ntsize. 

Transparently output the contentsof fi le fi i ename. Each line is output asitwould bewereit 

preceded by \i; however, the lines are not subject to copy-mode interpretati on. If thefile does not 

end with a newline, then a newl ine will beadded. Forexample, you can define a macro x 

contai ni ng the contents of fi le f , usi ng 

.dix 

.trff 

.di 

U nlikewith the et request, thefilecannot contai n characters such as nul that are not legai trotf 
input characters. 

Thisisthesameasthetr request except that the translati ons do not apply to text that is transpar- 
ently throughput into a diversion with H Forexample, 

.tr ab 
.di x 
U.tm a 
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.di 



.troff 



.vptn 



.whilecanyt hi ng 
.writes treamanythi n g 

EXTENDED REQUESTS 

. cf f i I e n a me 



will print t>; if trnt isused instead of tr, it will print a. 

M akethen built-in condition false; and the t bui It-i n condition true. Thisundoestheeffect of the 
nroff request. 

Enableverti cai position trapsif n isnonzero, disablethem otherwise. Vertical position trapsare 
trapsset by thewh or dt requests. Trapsset by theu request are not vertical position traps. The 
parameter that controis whether vertical position traps are enabled isglobal. Initially, vertical 
position traps are enabled. 

Control warnings. n isthesum of thenumbersassociated with each warningthat isto be enabled; 
ali other warnings will bedisabled. Thenumber associated with each warning islisted in the 
"Warnings" subsection. Forexample, .warn 0 will disableall warnings, and .warn 1 will disableall 
warnings except that aboutmissingcharacters. If n isnotgiven, ali warnings will be enabled. 
Whilecondition c istrue, accept a n y t h ng as input; c can beany condition acceptableto an if 
request; anyt hi ng can comprise multiple linesif the first linestartswith \{ and the I asti ine ends 
with \}. Seealso thebreak and continue requests. 

Writeanyt hi ng to thestream named stream. stream must previously havebeen thesubject of an 
open request. anyt hi ng isread in copy mode; a leadingwill be strippaci. 



When used in a di versi on, thiswill embed in thediversion an object which, when reread, will cause 
the contents off i e n a me to betransparently copi ed through to the output. In U N IX troff, the 
contentsof f i i e n a me are immediately copied through to the output regardlessof whether there isa 
current diversion; thisbehavior isso anomai ous that it must be considered a bug. 
.evxx If xx isnot a number, thiswill switch to a named environment called xx. Theenvironment should 

bepopped with a matching ev request without any arguments, just asfor numbered environments. 
There is no limiton thenumber of named environments; they will becreated the first ti me that 
they are referenced. 

.fpnfif 2 Thetp request hasan optional third argument. Thisargument givestheexternal nameof the font, 

which isused for finding the font description file The second argument gives the internai nameof 
the font, which isused to referto the font in troff after it has been mounted. If there is no third 
argument, then the internai namewill be used as the extern al name. Thisfeatureallowsyou touse 
fontswith long namesin compati bility mode. 

.ssmn When two arguments are given to the ss request, the second argument gives thesentence space size. 

If the second argument isnot given, thesentence space size will be the sameas the word space size. 
Liketheword spacesize, thesentencespaceisin unitsof onetwelfth of thespacewidtn parameter 
for the current font. Initially, both the word space size and thesentence space size are 12. The 
sentence space size isused in two circumstances: If the end of asentenceoccursattheend of a line 
in fili mode, then both an interword space and a sentence spacewill beadded; if two spacesfollow 
the end of a sentence in the middle of a line, then the second spacewill be a sentence space. N ote 
that the behavior of U N IX troff will beexactly that exhibited by GN U troff if a second argument 
is never given to the ss request. In GN U troff, asin U N IX troff, you should alwaysfollow a 
sentence with eitheranewlineortwo spaces. 

. tan 1n 2 . . .nnTr lr2. . .rn Settabsat pOSitionSnl , n2 , . . .,nn and then Settabsat nn+rl , n n +r 2 ,.. .., nn+rn and then at 

nn+m+ri, n n +r n +r 2 , . . . , n n +r n +r n , and so on. For example . ta t .sì will set tabs every half an 
inch. 




\n[.fam] Thecurrent fontfamily. Thisisastring-valued regi ster. 

\n[.fp] Thenumberof the nextfree font positi on. 

\n[.g] Alwaysi. M acrosshould use thisto determinewhetherthey are running under GNU troff. 

\n[.hia] Thecurrent hyphenation languageasset by the ma request. 

\n[ .me] Thenumberof immediately precedi ng consecutive hyphenated lines. 

\n[.him] The maximum allowed numberof consecutive hyphenated lines, asset by the nim request. 

\n[.hy] Thecurrent hyphenation flags (asset by the hy request.) 

\n[.hym] Thecurrent hyphenation margin (as set by the hym request.) 

\n[.hys] Thecurrent hyphenation space (as set by the hys request.) 

\n[ .in] Theindent that appliesto thecurrent output line. 

\n[.kem] 1 if pairwise kerning is enabled, 0 otherwise. 

\n[.ig] Thecurrent ligature mode (as set by the ig request.) 

\n[ .il] T he line length that appliesto thecurrent output line. 

\n[.it] T he title length assetbytheit request. 

\n[ .ne] Theamount of space that was needed in thelast ne request that caused atrap to besprung. Useful in 

conjunction with the \ n[ .trunc] regi ster. 
\n[ .pn] Thenumberof the next page eitherthevalueset by a pn request, or the numberof thecurrent page 

plus 1. 

\n[.ps] Thecurrent poi ntsize i n scaled points. 

\n[.psr] Thelast requested pointsizein scaled points 

\n[.rj] Thenumberof linesto beright-justified asset bytherj request. 

\n[.sr] Thelast requested pointsizein points as a decimai fraction. Thisisastring-valued register. 

\n[ .tabs] A string representation of thecurrent tab setti ngssuitablefor use asan argument to theta request. 

\n[. trunc] T he amount of vertical space truncated bythemostrecentlysprungvertical position trap, or, ifthetrap 
wassprung by an ne request, minus the amount of vertical motion produced by thene request. In other 
words, at the poi nt atrap issprung, it representsthedifferenceof what the vertical position would have 
been but for the trap, and what the vertical position actually is. Useful in conjunction with the\n[ .ne] 
register. 

\n[.ss] Thesegivethevaluesof theparametersset by the first and second argumentsof the ss request. 

\n[ .sss] 

\n[.vpt] 1 if vertical position traps are enabled, a otherwise 

\n[.warn] Thesum of the numbers associated with each of the currently enabled warnings. The num ber associ ated 

with each warning is listed in the"W arnings" subsection. 
\n(.x The major version number. Forexample, if theversion number is 1.03 then \n(.x will contain 1. 

\n(.y The minor version number. For example, if theversion number is 1.03 then \n(.y will contain 03. 
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Thefollowing registers are set by the\w escape sequence: 
\n[rst] 

\n[rsb] Likethest and sb registers, but takes account of the heights and depthsof characters. 

\n[ssc] Theamount of horizontal space ( possi bly negative) thatshould beadded to the last character beforea 

subscri pt. 

\n[skw] H owfar to right of the center of the last character in the\w argument, the center of an accentfrom a 

roman font should be placed over that character. 

Thefollowing read/writenumber registers are available: 

\n[systat] Thereturn valueof thesystemo function executed by the last sy request. 

\n[siimit] If greaterthan 0, the maximum number of objectson the input stack. If lessthan or equal to 0, there isno 
limit on the number of objectson the input stack. W ith no limit, recursion can continue unti I virtual 
memory isexhausted. 

MISCELLANEO US 

Fonts not listed in theDEsc file are automatically mounted on thenext available font position when they arereferenced. 
If a font isto be mounted explicitly with thetp request on an unused font position, it should be mounted on the first unused 
font position, which can befound in the \n[ .fp] register; although troff doesnot enforce this strictly, it will not allow a font 
to be mounted at a position whose number ismuch greaterthan that of any currently used position. 

Interpolati ng a stri ng doesnot hideexisting macro arguments. Thusin amacro, a more efficient way of doing 

.xx\\$@ 

is 

\\*[xx]\\ 

If the font description filecontainspairwisekerning information, characters from that font will bekerned. Kerning between 
two characters can be inhibited by placing a \& between them. 

In a stri ng compari son in a condì tion, characters that appear at different input levelsto the first deli m iter character will not 
berecognized asthesecond orthird delimiters. This appi iesalso to the ti request. In a \w escape sequence, a character that 
appears at a different input leve! to the starti ng deli m iter character will not berecognized as the dosi ng deli miter character. 
When decodinga macro argument that isdelimited by doublé quotes, a character that appears at a different input level to 
the starti ng deli miter character will not berecognized astheclosing del imi ter character. The implementation of \$e ensures 
that the doublé quotes surroundingan argument will appear the same input level, which will be different to the input level 
of the argument itself. In a long escape name] will not berecognized asaclosingdelimiterexceptwhen itoccursat the same 
input level astheopening ]. In compati bility mode, noattention ispaidto the input level. 

There are some new typesof condition: 

.itrxxx Trueif there is a number register named xxx. 

. ifdxxx Trueif there is a string, macro, diversion, or request named xxx. 

. if ce h Trueif there is a character eh available; eh iseither an ASCII character or a special character \(xx or uxxxj; the 
condition will also betrue if eh hasbeen defi ned by the chat- request. 

WARNINGS 

Thewarningsthat can begiven by troff aredivided into thefollowing categories. The name associ ated with each warningis 
used by the-w and -woptions; the number isused by thewarn request, and by the .warn register. 



chaM N onexistent characters. Thisisenabled by default. 

number2 Invalid numeric expressions. This isenabled by default. 

break4 In fili mode, lines which could not bebroken so thattheir length was lessthan the line length. Thisis 

enabled by default. 
deiim8 M issingor mismatched closing delimiters. 



gtroff 



el16 

scale32 

range64 

syntax128 

di256 

mac512 



regi 024 
tab2048 

right -brace4096 
missing8192 
input16384 
escape32768 

space65536 



font131072 
ig262144 



Useof theei requestwith no matchingie request. 
M eaningless scaling indicators. 
Out of rangearguments. 
Dubioussyntaxin numeri c expressi ons. 

Useof di or da without an argument when thereisno current diversion. 

Useof undefi ned strings, macros, and diversions. When an undefined stri ng, macro, or diversion isused, 
that string isautomatically defined asempty. So, in most cases, at most onewarning will begiven for each 
nama 

Useof undefined number registers. When an undefined number register isused, that register isautomati- 
cally defined to havea valueof 0. A definiti on isautomatically madewith a valueof 0. So, in most cases, at 
most onewarning will begiven for useof a particular name. 

I nappropriate use of a tab character. E i ther use of a tab character where a number was expected, or use of 
tab character in an unquoted macro argument. 

U se of \g where a number was expected. 
Requeststhat aremissing nonoptional arguments. 

II legai input characters. 

U nrecognized escape sequences. W hen an unrecognized escape sequenceisencountered, the escape 
character is ignored. 

M issing space between a request or macro and its argument. Thiswarningwill begiven when an 
undefined namelonger than two characters isencountered, and thefirsttwo characters of the name make 
a defined name. The request or macro will not beinvoked. When thiswarning isgiven, no macro is 
automatically defined. T hi sisenabled by default. Thiswarningwill never occur in compatibility mode. 
N onexistent fonts. This isenabled by default. 

Il legai escapes i n text ignored with theig request. These are conditions that are errors when they do not 
occur in ignored text. 



Therearealso namesthat can beused to referto groupsof warnings: 

ali Ali warnings except di, mac, and reg. It isintended that this co versali warni ngs that are useful with 

traditional macro packages. 
w Ali warnings 

INCOMPATIBILITIES 

Long names cause some incompatibilities. UNIX troff will interpret 

.dsabcd 

asdefining a string ab with contentscd. N ormally, GNU troff will interpret this as a cali of a macro named dsabcd. Also 
U N IX troff will interpret \*[ or\n[ as referencesto a string or number register called [. In GN U troff, however, this will 
normally beinterpreted as the start of a long name In compatibility modeGN U troff will interpret these thi ngs in the 
traditional way. In compatibility mode, however, long names are not recognized. Compatibility mode can beturned on with 
the-c command-lineoption, and turned on or off with thecp request. The number register \n(.c is 1 if compatibility mode 
ison, 0 otherwise. 

GNU troff does not allow the useof the escape sequences in names of strings macros, diversions number registers, fonts, or 
environments; UNIX troff does.The\A escape sequencemay behelpful in avoiding useof these escape sequences in names. 

Fractional poi ntsizes cause one noteworthy incompatibility. In U N IX troff theps request ignores scale indicators and so 

.ps 10U 



will set thepointsizeto 10 points, whereasin GNU troff itwill set the pointsize to 10 scaled points. 
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In GNU troff thereisafundamental difference between unformatted, input characters, and forni atted, output characters. 
Everything that affects how an output characterwi II be output isstored with thecharacter; after an output character hasbeen 
constructed, it isunaffected by any subsequent requests that are executed, including bd, cs, tkf, tr, ortp requests. Normally 
output characters are constructed from input characters at the moment immediately before the character isadded to the 
current output line. M acros, diversi ons, and stri ngs are ali, in fact, thesametypeof object; they contai n listsof input 
characters and output characters in any combinati on. An output character does not behave li kean input character for the 
purposes of macro processing; it does not inherit any of the special properties that the input character from which itwas 
constructed might havehad. For example, this: 

.di x 
\\\\ 
.br 
.di 
. x 

will print \\ in GN U troff; each pair of input \sisturned into one output \ and the resulti ng output \s are not interpreted 
as escape characters when they are reread. U N IX troff would interpret them as escape characters when they were reread and 
would end up printingone \.Thecorrectway to obtain a printable \ isto use the \e escape sequence: this will always print a 
si ngleinstanceof the current escape character, regardlessof whether or not it isused in adiversion; it wi II also work in both 
GNU troff and U N IX troff. If you wish for somereason to storein a diversion an escape sequence that will be i nterpreted 
when the diversion is reread, you can either use the traditional \! transparent output faci li ty, or, if thisisunsuitable, thenew 
\? escape sequence. 



ENVIRONMENT 

GROFF_TMAC_PATH 
GROFF_TYPESETTER 
GROFF FONT PATH 



A colon-separated list of directoriesin which to search for macro files. 
Default device. 

A colon-separated list of directoriesin which to search forthedevname directory, troff will search 
in directoriesgiven in the -f option before these, and in standard directories(:/usr/iib/groff/font, 
: /usr/iib/f ont, and : /usr/iib/f ont) after these. 



FILES 

/usr/lib/groff /f ont/devname/DESC 
/usr/lib/groff /tmac/ troff re 
/usr/lib/groff /tmac/tmac. name 
/usr/lib/groff /f ont/devname/DESC 
/usr/lib/groff /font I desinarne /F 

SEE ALSO 

groff(l) gtbl(l), gpic(l), geqn(l), grops(l), grodvi(l), grotty(l), grof f_f ont(5), grof f_out(5), grof f_cbar(7) 

GroffVersion 1.09, 14 February 1994 



I n i ti al i zati on file 
M acro fi les 

D evi cedescri ption fi le for device name 
Font fi le for font F of device name 



gzip, gunzip, zcatgzip, gunzip, zeat 

gzip, gunzip, zcatgzip, gunzip, zeat— C om press or expand files 
SYNOPSIS 

gzip [ -aedf blLnNrtvV19 ][-Ssuffix] [ name ... ] 
gunzip [ -acf blLnNrtvV ][-Ssuffix] [ name ... ] 
zeat [ -fhLV ] [name ... ] 



gzip, gunzip, zcatgzip, gunzip, zcat 
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gzip reducesthesizeof thenamed files usi ng Lempel-Ziv coding (LZ77). W henever possible, each file is replaced by one 
with theextension .gz, whilekeepingthesameownership modes, access, and modificati on times. (The default extension is 
-gz forVM S, z for M S-DOS, OS/2 FAT, Windows NT FAT and Atari.) If no files are specified, or if a filename is-, the 
standard input iscompressed to the standard output, gzip will only atterri pt to compress regular files. In particular, it will 
ignore symbolic links. 

If thecompressed filenameistoo long for its fi lesystem, gzip truncates it. gzip attemptsto truncate only the partsof the 
filename longer than threecharacters. (A part isdelimited bydots.) If thenameconsistsof small partsonly, the longest parts 
aretruncated. For example, if filenamesarelimited to 14 characters, gzip.msdos.exe iscompressed to gzi.msd.exe.gz. N ames 
arenottruncated on systemsthat do not havea limit on filename length. 

By default, gzip keeps the originai filename and timestamp in thecompressed file These are used when decom pressing the 
fi le with the-N opti on. Thisisuseful when thecompressed filenamewastruncated or when the timestamp wasnot preserved 
after a fi le transfer. 

Compressed files can berestored to their originai form using gzip -d or gunzip or zcat. If the originai namesaved in the 
compressed fi le is not suitable for its fi lesystem, a new nameisconstructed from the originai oneto makeit legai. 

gunzip takesa list of files on itscommand line and replaceseach filewhosenameendswith .gz, -gz, .z, -z, z, or .z and which 
beginswith thecorrect magic numberwith an uncompressed filewithouttheoriginal extension. gunzip also recognizesthe 
special extensions .tgz and .taz asshorthandsfor .tar.gz and .tar.z respectively. W hen compressing, gzip usesthe .tgz 
extension if necessary i nstead of truncatingafilewith a .tar extension. 

gunzip can currently decompress files created bygzip, zip, compress, compress -h, or pack. The detection of the input format 
isautomatic. When using the first two formats, gunzip checks a 32-bit CRC. For pack, gunzip checks the uncompressed 
length. The standard compress format wasnot designed to allow consistency checks. H owever, gunzip issometimesableto 
detectabad . z fi le If you getan errorwhen uncompressinga . z fi I e, do not assume that the .z file iscorrect simply because 
the standard uncompress does not compiai n. T hi sgenerally means that the standard uncompress doesnot check its input, and 
happily generates garbage output. T he SC 0 compress -h format (ìzh compression method) does not i nclude a C RC but also 
allows some consistency checks. 

Files created by zip can be uncompressed bygzip only if they have a si nglemember compressed with the deflation method. 
Thisfeatureisonly intended to help conversion of tar. zip files to the tar.gz format. To extract zip files with several 
members, useunzip i nstead of gunzip. 

zcat isidentical to gunzip -c. (On some systems, zcat may beinstalled asgzcat to preserve the originai link to compress.) 
zcat un com presseseither a list of files on thecommand line or its standard input and writes the uncompressed data on 
standard output, zcat will uncompress files that have thecorrect magic numberwhetherthey havea .gz suffixornot. 

gzip usesthe Lempel-Ziv algori thm used in zip and pkzip. Theamount of compression obtained dependson the size of the 
input and the distri bution of common substri ngs. Typically, text such assourcecodeor English isreduced by 60 to 70 
percent. Compression isgenerally much better than that achieved by LZW (asused in compress), H uffman coding (as used 
in pack), oradaptiveH uffman coding (compact). 

Compression isalways performed, even if thecompressed fileisslightly larger than the originai. The worst caseexpansion isa 
few bytesfor the gzip file header, plus 5 bytesevery 32KB block, or an expansion ratio of 0.015 percent for large files. N ote 
thattheactual number of used disk blocksalmost never increases. gzip preserves the mode, ownership, and timestampsof 
fileswhen compressing or decompressi ng. 

0PTI0NS 

-a -ascii ASCII textmode convert end-of-linesusing locai conventions.Thisoption issupported 

only on some non-U N IX systems. For M S-D 0 S, cr lf is converted to lf when compress- 
ing, and lf is converted to cr lf when decompressi ng. 

-c -stdout -to-stdout Writeoutput on standard output; keep originai files unchanged. Ifth ere are several input 

files, the output consistsof asequenceof independently compressed members. To obtain 
better compression, concatenate ali input files before compressing them. 
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d -decompress -uncompress 
f -force 



h -help 
1 -list 



L -license 



n -no-name 



N -name 



q -quiet 



r -recursive 



S .suf -suffix .suf 



t -test 
v -verbose 



V -version 
# -fast -best 



D ecompress. 

Force compression or d eco mp ressi on even if the fi le has multiple links or the correspondi ng 
filealready exists, or if thecompressed data isread from or written to a terminal. If the 
input data is not in a format recognized by gzip, and if the opti on -stdout isalso given, 
copy the input data without changeto the standard output; I et zcat behaveascat. If -f is 
not given, and when not running in the background, gzip promptsto verify whether an 
existi ng file should beoverwritten. 
D isplay a help screen and quit. 

Foreach compressed file, I ist the followi ng f ields: compressed size (size of thecompressed 
file), uncompressed size (size of the uncompressed file), ratio (compression ratio— 0.0% if 
unknown), uncompressed name (name of the uncompressed file). The uncompressed size is 
given as -1 forfilesnot in gzip format, sudi as compressed .z fi les. To get the uncompressed 
sizeforsuch a file, you can use: 
zcat file.Z | wc -c 

In combination with the -verbose option, thefollowing fields arealso displayed: method 
(compression method), ere (the 32-bitCRC of the uncompressed data), date & une 
(timestampfor the uncompressed file). The compression methodscurrently supported are 
deflate, compress, lzh (SCO compress -h) and pack. The ere is given aSffffffff for a file 
not in gzip format. 

With -name, the uncompressed name, date and timearethosestored within thecompressed 
fileif present. 

With -verbose, the size totals and compression ratio for ali fi les isalso displayed, unless 
somesizes are unknown. W ith -quiet, thetitleand totals lines are not displayed. 
D isplay the gzip license and quit. 

When compressing, do not save the originai filenameand timestamp by default. (The 
originai nameisalwayssaved if the name had to betruncated.) W hen decompressi ng, do 
not resto re the ori gin al filenameif present (remove only the gzip suffixfrom thecompressed 
filename) and do not resto re the ori gin al timestamp if present (copy itfrom thecompressed 
fi le). T his option isthe default when decompressi ng. 

When compressing, always save the originai filenameand timestamp; thi s is the default. 
When decom pressing, restare the originai filenameand timestamp if present. Thi s option is 
useful on systemsthat havealimit on filename length or when the timestamp hasbeen lost 
after a fi le transfer. 
Suppressall warnings. 

Trave! the directory structure recursively. If any of the f i I en am es speci fi ed on thecommand 
linearedirectories, gzip wi II descend into the directory and compressali the fi les it finds 
there (or decompress them i n the case of gunzip). 

Use suffix .suf instead of .gz. Any suffixean be given, but suffixes other than .z and .gz 
should beavoided to avoid confusion when filesaretransferred to other systems. A nuli 
suffix force gunzip to try decompression on ali given files regardlessof suffix, asin the 
followi ng: 

gunzip -s "" * (*.* for M S-DOS) 

P revious versi onsof gzip used the .z suffix. T his waschanged to avoid a confi ict with 
pack(l). 

Test. Check the compressed fi le i ntegrity. 

Verbose. D isplay the nameand percentagereduction foreach fi le compressed or decom- 



Version. D isplay the version numberand compilation options, then quit. 
Regulatethespeed of compression using the specified digit*, where-1 or --fast indicates 
thefastest compression method (less compression) and -9 or - -best indicatestheslowest 
compression method (best compression). Thedefault compression leve! is -6 (thatis, biased 
towardshigh compression atexpenseof speed). 



gzip, gunzip, zcatgzip, gunzip, zcat 



ADVANCED USAGE 

M ultiple compresseci filescan be concatenateci. In this case, gunzip will extractall membersat once. Forexample, 

gzip -c filel >foo.gz gzip -c file2»> foo.gz 

Then 

gunzip -c foo 
isequivalentto 

cat filel file2 

In caseof damageto onemember of a .gz file, other memberscan stili berecovered (if thedamaged member isremoved). 
H owever, you can get better compression by compressing ali members at once. 

cat filel file2 ] gzip > foo.gz 

compresses better than 
gzip -c filel file2 >foo.gz 

If you wantto recompress concatenated filesto get better compression, use 

gzip -ed old.gz j gzip > new.gz 

If a compresseci fi le consists of several members, theuncompressed sizeandCRC reported bythe-iist option appliesto the 
last member only. If you need theuncompressed size forali members, you can use 
gzip -ed file.gz j wc -c 

If you wish to create a single archi ve file with multiple members so that memberscan later beextracted independently, usean 
archiver such astar or zip. GNU tar supportsthe -z option to invokegzip tran sparenti y. gzip isdesigned asacomplement 
to tar, not as a replacement. 

ENVIRONMENT 

The envi ronment variable gzip can hold a set of default options for gzip. T hese options are i nterpreted fi rst and can be 
overwritten by explicit command-lineparameters. Forexample 

For sh: GZIP=" -8v -name" 

Export GZIP for csh: setenv GZIP " -8v -name" 

For MS-DOS: set GZIP=-8v -name 

On Vax/VM S, the name of the envi ronment variable ìsgzip_opt, to avoid a confi ict with the symbol set for invocation of the 
program. 

SEEALSO 

znew(l), zcmp(l), zmore(l), zforce(l), gzexe(l), zip(l), unzip(l), compress(l), pack(l), compact(l) 

DIAGNOSTICS 

Exit status isnormally 0; if an errar occurs, exit status i si. If awarning occurs, exit status is 2. 

Usagegzip [-cdfhlLnNrtvV19] [-Ssuffix] [file ...] 

Invalid options were specified on thecommand line. 

file: not in gzip format 

Thefile specified to gunzip hasnot been compressed. 

file: Corrupt input. Use zcat to recover some data. 

The compressed f i le has been damaged. The data up to the poi nt of fai Iure can be recovered usi ng 

zcat file > recover 
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file: compresseci with xx bits, can only handle yy bits 

file was compresseci (using LZW) by a program that could deal with more bits than the decompress code on this machine. 
Recompressthefilewith gzip, which compresses better and uses lessmemory. 

file: already has .gz suffix--no change 

Thefileisassumed to be already compressed. Renarne the fi le and try again. 
file already exists; do you wish to overwrite (y or n)? 
Respond y if you want the output file to bereplaced; n if not. 

gunzip: corrupt input 

A SIGSEGV violation wasdetected, which usually meansthat the input file has been corrupted. 

XX. x% 

Percentageof the input saved by compression. (Relevant only for-v and -I.) 

- not a regular file or directory: ignored 

When the input fi le is not a regular fi le or directory, (such asasymbolic link, socket, FIFO, devi ce fi le), it isleft unaltered. 

- has xx other links: unchanged 

The input file has links; it is left unchanged. See ln(l) for more information. 
Use the -f flag to force compression of fi les that are multi ply linked. 

CAVEATS 

When writing compressed datato a tape, it isgenerally necessary to pad the output with zeroesup to a block boundary. 
When the data isread and the whole block ispassed to gunzip for decompression, gunzip detects that thereis extra trai li ng 
garbage after the compressed data and emitsawarning by default. You haveto usethe-quiet option to suppressthe 
warning. Thisoption can be set in theGzip environmentvariableasin thefollowing: 

for sh: GZIP="-q" tar -xfz -block-compress /dev/rst0 for csh: 
(setenv GZIP -q; tar -xfz -block-compr /dev/rst0 

In the precedi ng example, gzip isinvoked implicitly by the -z option of GN U tar. M ake sure that the same block size (b 
option of tar) isused for reading and writing compressed data on tapes. (This example assumes you are using theGN U 
versi on of tar.) 

BUGS 

The -list option reports incorrect sizes if they exceed two gigabytes. The -list option reportssizesas -1 and ere asffffffff 
if the compressed fi le i s on a nonseekable media. 

In some rare cases, the-best option givesworse compression than the default compression level (-6). On somehighly 
redundant fi les, compress compresses better than gzip. 

Locai 

gzexe 

gzexe— Compress executablefiles in place 
SYNOPSIS 

gzexe [ name ... ] 



head 
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Thegzexe utility enablesyou to compress executables in place and havethem automatically uncompress and executewhen 
you run them (at a penalty in performance). For exampleif you executegzexe /bin/cat, it will create the followingtwo files: 

-r-xr-xr-x 1 root bin 9644 Feb 11 11:16 /bin/cat 
-r-xr-xr-x 1 bin bin 24576 Nov 23 13:21 /bin/cat" 

/bin/cat" is the origi nal fileand /bin/cat istheself-uncompressing executable file You can remove /bin/cat" when you are 
sure that /bin/cat works properly. 

Thisutility ismost useful on systemswith very small disks. 
OPTIONS 

-d Decompressthegiven executables instead of compressing them 
SEEALSO 

gzip(l), znew(l), zmore(l), zcmp(l), zforce(l) 

CAVEATS 

The compresseci executable is a sh eli script. Thismay create some security holes. In particular, the compresseci executable 
relieson thePATH environment variableto find gzip and some other Utilities (taii, cnmod, in, sieep). 

BUGS 

gzexe attemptsto retai n the origi nal file attri butes on thecompressed executable, but you may haveto fixthem manually in 
somecases, using cnmod or cnown. 

head 

head— 0 utput the fi rst part of fi les 
SYNOPSIS 

head [-c N[bkm]] [-n N] [-qv] [ - -bytes=N[bkm] ] [--lines=N] [--quiet] [--silent] 
[--verbose] [--help] [--version] [file...] 

head [-Nbcklmqv] [file...] 

D ESC RIFIO N 

Thismanual page documents the GN U version of head, head prints the first part (10 linesby default) of each given file; it 
readsfrom standard input if no fi les are given or when afilenameof - isencountered. If morethan onefi le is given, it prints 
a header consisti ngof the fi le'snameenclosed in ==> and <== befo re the output for each file. 

OPTIONS 

head acceptstwo option formats: thenew one, in which numbersareargumentsto theoption letters; and the old one, in 
which the number precedes any option letters. 

-c n, --bytes n PrintfirstN bytes. n isanonzero integer, opti onally followed by oneof thefollowing charactersto 

speci fy adifferentunit. 

b 512-byte blocks. 

k 1-kilobyte blocks. 

m 1-megabyte blocks. 
-ì, -n n, --ìines n PrintfirstN lines. 
-q, - -quiet, --siient N ever print filename headers. 
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-v, -verbose Always print filmarne headers. 

-heip Print ausagemessageand exit with a nonzero status, 

--version Print version information on standard output, then exit. 

GNU TextUtilities 



hexdump 

hexdump— ASCII, decimai, hexadecimal, octal dump 
SYNOPSIS 

hexdump [-bcdovx] [-e f ormat_string] [-f format_file] [-n length] [-s skip] [file ...] 

DESCRIPTION 

The hexdump utility is a fi Iter that displays the specified files, or the standard input, if no filesarespecified, in auser-specified 
format. 

Theoptionsareasfollows: 

-b One-byte octal display. D isplay the input offset in hexadecimal, followed by sixteen space- 

separated, three-column, zero-fi lied bytesof input data, in octal, per line, 
-c One byte character display. D isplay the input offset in hexadecimal, followed by sixteen space- 

separated, three-column, space-fi Ned, charactersof input data per line, 
-d Two-byte decimai display. Display the input offset in hexadecimal, followed by eight space- 

separated, five-column, zero-fi lied, two-byte uni tsof input data, in unsigned decimai, per line 
Specify a format stri ngto beused for displayingdata. 

Specify a file that contains one or morenewlineseparated format stri ngs. Empty linesand lines 
whosefirstnonblankcharacterisahash mark (#) areignored. 
I nterpret only length bytesof input. 

Two-byte octal display. Display the input offset in hexadecimal, followed by eight space-separated, 
six-column, zero-fi lied, two-byte quantitiesof input data, in octal, per line. 
Skip offset bytesfrom the beginningof the input. By default, offset isinterpreted as a deci mal 
number. W ith a leading ox or ex, offset isinterpreted asa hexadecimal number; otherwise, with a 
leading 0, offset isinterpreted asan octal number. Appendi ng the character b, k, or m to offset 
causesit to beinterpreted asa multi pie of 512, 1024, or 1048576, respectivéy. 
-v The -v option causes hexdump to display ali input data. Without the -v option, any number of 

groups of output lines, which would be identical to the immediately preceding group of output 
li nes(except for the input offsets), arereplaced with a li ne compri sed of a single asterisk. 
-x Two-byte hexadecimal display. D isplay the input offset in hexadecimal, followed by eight, space- 

separated, four-column, zero-fi Ned, two-byte quantitiesof input data, in hexadecimal, per line. 

Foreach input file hexdump sequentially copies the inputto standard output, transforming the data accordingto theformat 
stri ngs specified by the -e and -f options, in the order that they were specified. 

FORM ATS 

A format stri ng contains any number of format units, separated by whitespace. A format unit contai nsup to three items: an 
iteration count, a bytecount, and a format. 

Theiteration count isan optional positive integer, which defaultsto one. Each format isapplied iteration counttimes. 

T he byte count isan optional positive integer. If specified, itdefines the number of bytesto beinterpreted byeach iteration 
of theformat. 



-e format_string 
-f format_file 

-n length 
-0 

-s offset 



hexdump 




If an iteration count and/or a bytecount isspecified, a si ngle slash must beplaced after the iteration count and/or beforethe 
byte count to disambiguatethem. Any whitespace before or after the slash is ignored. 

Theformat is required and must besurrounded by doublequote(" ") marks. It is interpreted asan fprintf-style format 
string(seefprintf(3)) with thefollowingexceptions: 

■ An asterisk (*) may not beused asafield width or precision. 

■ A bytecount orfield precision is required for each s conversi on character (unii ke the f printf (3) default, which prints 
the enti re stri ng if the precision isunspecified). 

■ The conversi on charactersti, 1, n, p, and q are not supported. 

■ T he si ngle- character escape sequencesdescribed intheC standard are supported: 



NUL 


\0 


Alert character 


\a 


Backspace 


\b 


Form-feed 


\f 


N ewline 


\n 


C arri age return 


\r 


Tab 


\t 


V erti cai tab 


\v 



hexdump also supports the following additional conversion strings: 

a[dox] D i splay the input offset, cumulati ve across input fi les, of thenext byteto bedisplayed. Theappended characters 

d, o, and x speci fy the di splay base as deci mal, octal, or hexadecimal respectively. 
A[doxi Identical to the a conversion stri ng exceptthat it isonly performed once, when ali of the input data hasbeen 

processed. 

c Output characters in the default character set. N onprinting characters are displayed in th ree- character, zero- 

padded octal, except for thoserepresentableby standard escape notati on (see precedi ng list), which are displayed 
as two-character strings. 

p Output characters in the default character set. N onprinting characters are displayed as a single peri od. 

u 0 utput U .S. ASC 1 1 characters, with the exception that control characters are displayed using the lowercase names 

in the following mini-table. C haracters greater than exff, hexadecimal, are displayed as hexadecimal strings. 



000 


nul 


001 


soh 


002 


stx 


003 


etx 


004 


eot 


005 


enq 


006 


ack 


007 


bel 


008 


bs 


009 


ht 


00A 


lf 


00B 


vt 


00C 


ff 


00D 


cr 


00E 


so 


00F 


si 


010 


die 


011 


dd 


012 


dc2 


013 


dc3 


014 


dc4 


015 


nak 


016 


syn 


017 


etb 


018 


can 


019 


em 


01A 


sub 


01B 


esc 


01 C 


fs 


01D 


gs 


01E 


rs 


01 F 


US 


0FF 


del 















Thedefault and supported byte counts for the conversion characters are asfollows: 
%_c %_p, %_u, %c 0 ne byte counts only. 

%d, %i, %o, %u, %x, %x Four-byte default; one-, two-, and four-byte counts supported. 
%e, %e, %f , %g, %g E ight-byte default, four-byte counts supported. 

Theamount of data i nterpreted by each format stri ng isthesum of the data required by each format uni t, which isthe 
iteration count times the byte count, or the iteration count ti mesthe number of bytes required by theformat if the byte 
count is not speci fi ed. 

The input is manipulated in blocks; a block isdefined as the largest amount of data speci fi ed by any format stri ng. Format 
strings interpreti ng lessthan an input block'sworth of data, whoselast format unit both interprets some number of bytes 
and doesnot have a specified iteration count, have the iteration count incremented until the enti re input block hasbeen 
processed or thereis not enough data remai ni ng in the block to satisfy theformat string. 
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If, either asa result of user specifi cation or hexdump modifyingtheiteration count asdescribed, an iteration count i s greater 
than one, no trailing whitespacecharacters are output during the last iteration. 

It isan errar to specify a byte count aswell as multi pie conversion characters or strings unless ali but one of the conversi on 
characters or strings is a or a. If, asa result of the specifi cation of the -n option or end-of-file bang reached, input data only 
parti al ly satisfies a format stri ng, the input block iszero-padded sufficiente to display ali avai lable data (that is, any format 
unitsoverlappingtheend of data will display somenumberof thezero bytes). 

Further output by such format strings is replaced by an equivalent number of spaces. An equivalent number of spaces is 
defined asthe number of spaces output by an s conversion character with thesamefield width and precision as the originai 
conversion character or conversion stri ng but with any +, " ", # conversion flag characters removed, and referencingaNULL 
string. 

If no format strings are specifi ed, the default display isequivalentto specifying the -x option. 
hexdump exitse on success and >e if an errar occurred. 

EXAMPLES 

Display theinputin perusal format: 

"%06.6_ao " 12/1 "%3_u " 

"\t\t" "%_p 11 

"\n" 

lmplementthe-x option: 

"%07.7_Ax\n" 

"%07.7_ax " 8/2 "%04x " "\n" 

SEEALSO 

adb(l) 

18 Aprii 1994 



hipstopgm 

hipstopgm— Convert a H IPS fileinto a portablegraymap 
SYNOPSIS 

hipstopgm [hipsfile] 

D ESC RIFIO N 

Hipstopgm reads a H I PS file as input and produces a portable graymap as output. 

If the H IPSfilecontainsmorethan oneframein sequence, hipstopgm will concatenate ali theframes vertically. 
HIPS is a format developed attheHuman Information Processing Laboratory, NYU. 

SEEALSO 

pgm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

24 August 1989 




host 

host— Look up hostnamesusing domain server 
SYNOPSIS 

host [-1] [-v] [-w] [-r] [-d] [-t querytype] [-a] host [ server ] 

D ESC RIFIO N 

host looksfor information about Internet hosts. It getsthis information from a set of interconnected serversthat arespread 
across the country. By default, it simply converts between hostnamesand Internet addresses. H owever with the -t or -a 
options, it can beused to find ali of the information about this host that ismaintained by the domain server. 

Theargumentscan beeither hostnamesor host numbers. The program first attemptsto interpretthem as host numbers. If 
this fai Is, it will treat them ashostnames. A host number consistsof first decimai numbers separated by dots, for example, 
128.6.4.194. A hostname consistsof names separated by dots, for example, topaz.rutgers.edu. U nlessthenameendsin a 
dot, the locai domain isautomatically tacked on the end. Thus, a Rutgersuser can say "host topaz", and it will actually look 
up topaz.rutgers.edu. If thisfails, thenameistried unchanged (in thiscase, topaz). Thissameconvention isused for mail 
and other network Utilities. The actual suffixto tack on the end isobtained by looking at the resultsof a hostname cali, and 
usi ng everything starti ng at the first dot. (Following isadescription of how to customize the hostname lookup.) 

The first argument is the hostname you want to look up. If this is a number, an inverse query isdone; that is, the domain 
system looksin a separate set of databases used to convert numbers to names. 

Thesecond argument is optional. It allowsyou to speci fy a parti cular server to query. If you don't specify this argument, the 
default server (normally the locai machine) isused. 

If a nameisspecified, you may see output of threedifferent kinds. H ereisan example that shows ali of them: 

% host sun4 

sun4.rutgers.edu is a nickname for ATHOS.RUTGERS.EDU 
ATHOS.RUTGERS.EDU has address 128.6.5.46 
ATHOS.RUTGERS.EDU has address 128.6.4.4 
ATHOS.RUTGERS.EDU mail ìs handled py ARAMIS.RUTGERS.EDU 

The user hastyped thecommand host sun4. The first Iineindicatesthatthenamesun4.rutgers.edu is actually a nickname. 
Theofficial hostnameisATHos.RUTGERs.EDu. Thenexttwo lines show the address. If asystem hasmorethan onenetwork 
interface, therewill bea separate address for each. Thelast lineindicatesthatATHos.RUTGERs.EDu doesnot receiveitsown 
mail. M ai I for it istaken by aramis.rutgers.edu. There may bemorethan onesuch line, assomesystems havemorethan one 
other system that will handle mail for them. Technically, every system that can receive mail issupposed to havean entry of 
thiskind. If the system receivesitsown mail, there should bean entry the menti ons the system itself, for example "XXX mail 
is handled by XXX." H owever many systemsthat receive their own mail do not bother to mention that fact. If asystem has a 
"mail is handled by" entry, but no address, this indicates that it isnot really part of the Internet, but a system that ison the 
network will forward mail to it. Systems on U senet, bitnet, and a number of other networkshaveentriesof thiskind. 

There are a number of options that can be used before the hostname. M ost of these options are meaningful only to the staff 
who haveto maintain the domain database. 

The opti on -w causes host to wait forever for a response. N ormai ly itwill timeout after around a minute. 

Theoption -v causes printout to bein a verbose format. This is the officiai domain master fi le format, which isdocumented 
in the man page for named. Without thisoption, output stili follows this format in general terms, but someattempt ismade 
to makeit more i ntel li gi ble to normal users. Without -v, a, mx, and cname recordsarewritten out ashas address, man is 
handled py, and is a nickname for, and TT L and class fields are not shown. 

Theoption -r causes recursion to beturned off in the request. This means that the name server will return only data it has in 
itsown database. Itwill not ask other servers for more information. 

Theoption -d turnson debugging. N etwork transactions are shown in detail. 
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The opti on -t allowsyou to specify a particular typeof information to belooked up. Theargumentsaredefined in the man 

page for named. C urrently Supported types are a, ns, md, mf , cname, soa, mb, mg, mr, nuli, wks, ptr, hinf o, minto, mx, uinfo, uid, 

gid, unspec, and the wi Idcard, which may bewritten aseither any or*. Types must begiven in lowercase. N otethat the 
default isto look first for a, and then mx, except that if the verbose opti on isturned on, the default isonly a. 

Theoption -a (for "ali") isequivalentto -v -t any. 

Theoption -1 causes a listingof a complete domain. Forexample 

host -1 rutgers.edu 

will gi ve a listingof ali hostsin therutgers.edu domain. The -t option isused to fi Iter what information ispresented, asyou 
would expect. The default isaddress information, which also include PTR and N S records. Thecommand host: 

-1 -v -t any rutgers.edu 

will give a complete download of the zone data for rutgers.edu, in the offici al master fi le format. (H owever the SO A record 
is listed twice for arcane reasons.) 



NOTE 



-i is implemented by doing a complete zone transfer and then fi Iteri ng out the information you haveasked for. This 
command should be used only if it is absolutely necessary. 



CUSTOMIZING HOSTNAME LOOKUP 

In general, if thenamesupplied by the user does not nave any dots in it, a default domain isappended to the end. This 
domain can bedefined in /etc/resoiv.cont, but isnormally cleri ved by taking the locai hostname after its first dot. The user 
can overridethis, and specify a different default domain, usi ng the environment vari ablei_ocALDOMAiN. In addition, the user 
can supply hisown abbreviationsfor hostnames. They should bein a file consisti ngofone line per abbreviation. Each line 
containsan abbreviation, aspace, and then the full hostname. Thisfile must bepointed to by an environment vari able 
hostaliases, which is the name of the fi le. 

SEE ALSO 

named(8) 

BUGS 

U nexpected effectscan happen when you typea name that is not part of the locai domain. Pleasealwayskeep in mind that 
the locai domain nameistacked onto the end of every name unlessit endsin a dot. Only if this fai Isis the name used 
unchanged. 

The -ì option only tries the first name server listed for the domain that you haverequested. If this server isdead, you may 
need to specify a server manually. Forexample, to get a listingoftoo.edu, you could try host -t ns too.edu to get a list of ali 
thenameserversfortoo.edu, and then try host -ì too.edu xxx for ali xxx on the list of nameservers, until you find onethat 
works 

hostid 

hostid— Set or print system's host I D . 
SYNTAX 



hostid [-v] [ deci ma I - i d ] 



hostname 



D ESC RIFIO N 

Thehostid command printsthecurrent host I D number in hexadecimal and both decimai and hexadecimal in parenthesisif 
the-v option isgiven. Thisnumeric valueisexpected to beuniqueacrossall hostsand isnormally set to resemblethehost's 
Internet address. 

Only thesuperuser can set thehostid by givingan argument. This valueisstored in thefile/etc/hostid and need only be 
performed once. 

AUTHOR 

hostid iswritten by M itch D'Souza(m. dsouzaemrc-apu.cam.ac.uk). 

SEEALSO 

gethostid(2), sethostid(2) 

hostname 

hostname— Show or set the system's hostname 
dnsdomainname-Show the system's domai n name 

SYNOPSIS 

hostname [-d] [- -domain] [-Ff i I ename ] [ - -filef i I e n a me ] [-f ] [ - -fqdn] [-h] [ - -help] 

[ - -long] [-s] [ - -short] [-v] [ - -version] [name] 

dnsdomainname 

DESCRIPTION 

hostname is the program that isused to either set the hostname or display the current host or domain name of the system. 
This name isused by many of the networking programsto identify the machine 

When called without any arguments, the program displays the current name as set by the hostname command. You can 
change the output formatto display always the short or the long hostname (FQD N ). When called with arguments, the 
program will set thevalueof the hostname to the vai u e speci fi ed. This usually isdone only once, at system startup time, by 
the /etc/rc.d/rc.ineti confi guration script. 

N ote that only the superuser can change the hostname. 

If the program was called as dnsdomainname, it will show the domain name server (D N S) domain name. You can't change the 
D N S domain name with dnsdomainname. (Seethefollowing subsection.) 

OPTIONS 

-d, -domain D isplay the name of the D N S domai n. D on't use the com-mand domainname togettheDNS 

domain name becauseit will show the N IS domain name and not theDNS domain name 
-f, --file tiiename Read the hostname from the specified file. C omments (li nes starti ng with a #) are ignored. 
-t, - fqdn, - long D isplay the FQ D N (fully-qualified domain name). An FQ D N consists of a short hostname and 
theD N S domain name. U nlessyou are usi ng bind or N ISfor host lookups, you can change the 
FQD N and theDN S domain name(which is part of the FQDN) in the/etc/hosts file. 
Printausagemessageon standard output and exit successfully. 
D isplay the short hostname 

Print version information on standard output and exit successfully. 



-h, 


- -help 


-s, 


-short 


-v, - 


-version 


FILES 





/etc/hosts 
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AUTHOR 

Peter Tobias, (tobias@server.et-inf.fho-emden.de) 

Linux, 28 J uly 1994 

hpcdtoppm v0.3 

hpcdtoppm v0.3— Converta Photo-C D fileinto a portablepixmap 
SYNOPSIS 

hpcdtoppm [options] pcd-file [ppm-file] 

DESCRIPTION 

hpcdtoppm reads a Photo-C D imagefileor overview file, and outputs a portablepixmap. Imagefilesyou can find on the 
Photo-CD in photo_cd/images arenamed asimgnnnn .pcd, wherennnn isa 4-digit-number. TheOverview fileisatphoto_cd/ 
overview. pcd. If there is no ppm-fiie given, output will be printed to stdout. hpcdtoppm standsfor "H admut'spcdtoppm" to 
makeit di sti nguishable i n case so meo ne else is building thesamething and calli ng it pcdtoppm. 

OPTIONS 

-i Gi ve some informati on from thefileheaderto stderr. It worksonly for imagefiles. (It isnot 

working correctly, just printing some strings.) 
-s Apply simplesharpness-operator on thelumachannel. 

-d Do not show the complete image, but only thedecompressed difference. It worksonly on 

the4Baseand the 16Base resolution. It does not haveany deeper sense, but itwassimpleto 
implement and it showswhat causesdifferent sizesof imagefiles. 

-r Rotatethepictureclockwisefor portraits. 

-ì Rotatethepicturecounter-clockwisefor portraits 

-a T ry to fi nd out the image orientation. T hi sdoesn't work for overview filesyet. It isvery 

experimental and dependson onebyte. Pleasetell meif itdoesn'twork. 

-x Overskip mode. Workson Base/16, Base/4, Base, and 4Base. In Photo-CD images, the 

lumachannel isstored in full resolution, thetwo chromachannelsarestored in half 
resolution only and haveto beinterpolated. In the Overskip mode, thechromachannelsof 
thenext higher resolution aretaken instead of interpolati ng. To see the difference, generate 
oneppm with and oneppm without thisflag. Usepnmarith to generate the difference imageof 
thesetwo images. Cali ppmhist for this difference or show itwith xv (push theH istEq 
button in the color editor). 

-1 | -Base/16 | -128x192 Extract the Base/16 size picture (size 128x192 pixels). N ote that you can only give one size 
option. 

-2 ; -Base/4 ; -256x384 Extract the Base/4 size picture. 
-3 ! -Base j -512x768 Extractthe Basesize picture. 

-4 | -4Base | -1024x1536 Extract the 4Base size picture. 
-5 | -i6Base | -2048x3072 Extract the 16Basesize picture. 

-e | -overview j -o Extract ali pictures from an 0 verview file. A ppm filmarne must be given. If the given name 

istoo, the fi les arenamed foonnnn, wherennnn i s a 4-di git number. They arestored in 
Base/16 format, so they are extracted in thisformat. 

-ycc Suppress the ycc to rgb conversi on. T hi s is experimental only. You can usethisand apply 

ppmtorgb3 on the file. Then you will get threepgm fi les, oneluma and two chromafiles. 



httpd 



BUGS 

I stili don't haveenough information about the Photo-C D to takecareof ali data structures. The informati on I haveisquite 
vagueand thisprogram wasdeveloped by staringatthehexdumpsand usingthefamoustrial-and-error-method. :-) If 
anything doesn't work, pleasesend me a report and perhapsyou could try to find out why it doesn't work. 

SEEALSO 

ppm(5), ppmquant(l), ppmtopgm(l), ppmhist(l), pnmarith(l), ppmtorgb3(l), xv(l) 

AUTHOR 

Copyright© 1992 by H admut Danisch (danischeira.uka.de). Permission to use and distri butethis software and its 
documentation for noncommerci al use and withoutfeeishereby granted, provided that the preceding copyright notice 
appear in ali copi es and that both that copyright notice and this permission notice appear in supporting documentation. 
T his software may not besold in anyway. This software isnot public domain. 

28 Novemberl992 



httpd 



httpd— Apache Hypertext Transfer Protocol server 
SYNOPSIS 

httpd [ -vX? ] [-d s er ver r oot ][-f confi g ] 

DESCRIPTION 

httpd is the Apache H ypertext Transfer Protocol (HTTP) server process. The server may beinvoked by the Internet daemon 
inetd(lM ) each ti me a connection to the HTTP serviceismade, or alternati vely it may run as a daemon. 

OPTIONS 

-d serverroot Set the i ni ti al value for the serverRoot variableto serverroot. Thiscan beoverridden by theserverRoot 

command in theconfiguration file. Thedefault is/usr/iocai/etc/httpd. 
-f confi g Executethecommandsin thefileconf i g on startup. If confi g doesnot begin with a /, then it istaken to 

bea path relative to theserverRoot. Thedefault isconf/httpd.cont. 
-x Run in single- process mode, for internai debugging purposesonly; the daemon doesnot detach from the 

terminal or fork any children. D o not use this mode to provide ordì nary W eb servi ce. 
-v Printtheversion of httpd, and then exit. 

-? Print a list of the httpd options, and then exit. 

FILES 

/ usr /locai/ et c/ httpd /conf / httpd. conf 
/ usr /locai/ et c/ httpd /conf /srm.conf 
/ usr /locai/ et ci httpd /conf /access. conf 
/ usr /locai/ et ci httpd /conf /mime. types 
/usr/local/ et ci httpd /logs/error_log 
/usr /locai/ et ci httpd /logs/access_log 
/usr /locai/ et ci httpd /logs/httpd.pid 

SEEALSO 

inetd(lm) 

Documentation fortheApacheHTTP server isavailablefrom http://www.apache.org. 



October 1995 
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icontopbm 

icontopbm— Converta Sun icon into a portable bitmap 



SYNOPSIS 

icontopbm [iconfile] 

D ESC RIFIO N 

icontopbm readsaSun icon asinput and producesa portable bitmap as output. 
SEEALSO 

pbmtoicon(l), pbm(5) 

AUTHOR 

Copyright® 1988 byjef Poskanzer 

31 August 1988 

ident 

ident— I denti fy RCS keyword stringsin files 
SYNOPSIS 

ident [ -q ][-V ] [f i I e ... ] 

D ESC RIFIO N 

ident searchesfor ali instancesof the pattern $ keyword : text $ in thenamed filesor, if no files are named, thestandard 
input. 

Thesepatternsarenormally inserted automati cally bytheRCScommand co(l), butcan also beinserted manually.The 
option -q suppressesthewarninggiven ifthere areno patternsin a file. Theoption -v prints ident 's versi on number. 

ident works on text files aswell asobject files and dumps. Forexample, if the C program in f .c contains 

#include <stdio.b> 

static char const rcsid[] = 

"$Id: f.c.v 5.4 1993/11/09 17:40 eggert Exp $"; 

int main() { return printf ( "%s\n" , rcsid) == EOF; } 

and f .c iscompiled into f .0, then thecommand 
ident f.c f.o 
will output 

f.c: 

$Id: f.c.v 5.4 1993/11/09 17:40 eggert Exp $ 
f.o: 

$Id: f.c.v 5.4 1993/11/09 17:40 eggert Exp $ 

If aC program defi nes a stri ng I i ke the rcsid butdoesnotuseit, iint(l) may complain, and someC compilerswill optimize 
away the stri ng. The most reliable solution isto have the program use the rcsid stri ng, asshown in theexample. 

ident finds ali instancesof the $ keyword : text $ pattern, even if keyword isnotactuallyan RCS-supported keyword. This 
givesyou information about nonstandard keywordslike $xconsortium$. 



i Ibmtoppm 




KEYWORDS 

H ere is the list of keywordscurrently maintained by co(l). Ali timesaregiven in Coordinateci U ni versai Time (UTC, 

so meti mescali ed GMT by default), but if thefileswerechecked outwith co's-zzone option, timesaregiven with anumeric 

timezoneindication appended. 



$Author$ 


Thelogin nameof the user who checked in the revision. 


$Date$ 


Thedateand ti me the revision was checked in. 


$Header$ 


A standard headercontainingthefull pathnameof the RCS file, the revision number, thedateand time, 




the author, the state, and the locker (if locked). 


$Id$ 


Same as$Header$, except that the RC S filmarne is without a path. 


$Locker$ 


Thelogin nameof the user who locked the revision (empty if not locked). 


$Log$ 


The log messagesupplied during checkin. For ident's purposes, thisisequivalent to $Rcsme$. 


$Name$ 


Thesymbolic nameused to check out the revision, if any. 


$RCSfile$ 


T he name of the RC S file without a path. 


$Revision$ 


The revision number assigned to the revision. 


$Source$ 


Thefull pathnameof the RC S file. 


$State$ 


The state assigned to the revision with the-s option of rcs(l) or ci(l). 



co(l) representsthefollowing characters in keyword values by escape sequences to keep keyword stri ngs wel I formed. 

Character Escape Sequence 

Tab \t 
Newline \n 
Space \040 

$ \044 

\ \\ 

IDENTIFICATION 

Author: Walter F. Ti chy 

M anual Page Revision: 5.4; Release date September 11, 1993. 

Copyright© 1982, 1988, 1989 Walter F. Tichy. Copyright® 1990, 1992, 1993 Paul Eggert. 
SEEALSO 

ci(l), co(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), rcsfile(5) 

Walter F. Tichy, RCS- A System for Version Control, Software- Practice & Experiencel5, 7 (July 1985), 637-654. 

GNU,9Novemberl993 

ilbmtoppm 

ilbmtoppm— Con vertan ILBM fileintoaportablepixmap 
SYNOPSIS 

ilbmtoppm [ -verbose] [ -ignore<chunkID>] [ -isham| -isehb] [ -adjustcolors] [ILBMfile] 

D ESC RIFTIO N 

ilbmtoppm reads an IFF ILBM fi le as input and produces a portable pixmap as output. Supported ILBM types are N ormai 
ILBM swith 1-16 planes. 
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Amiga Extra Halfbrite (E HB) 
Amiga HAM with 3-16 planes 
24-bit 

M ultiplatte (normal or HAM ) pictures 
Colormap (bmhd and cmap chunk only, nPianes = 0) 
Unofficial direct color; 1-16 piane; foreach color component. 

Chunksused: bmhd, cmap, camg (only HAM and EH B flagsused), pchg, body unofficial dcol chunk to 

identify direct color I LBM 
C hunks ignored: grab, dest, sprt, crng, ccrt, clut, dppv, drng, epsf 

Other chunks (ignored but 
displayed in verbose mode): name, auth, (d), anno, dpi 
U nknown chunks are skipped. 

OPTIONS 

-verbose G ive some information about the I LBM file. 

-ignore <chunkiD> Skip achunk. <chunkiD> is the 4-letter iff chunk identifier of the chunk to be skipped. 
-isham | -isehb Treat theinput file as a ham or Extra H alfbrite picture, even if theseflags or not set in the camg 

chunk (or if there is no camg chunk). 
-adjustcolors If ali colors in the cmap haveavalueof lessthen 16, iibmtoppm assumesa4-bit colormap and givesa 

warning. W ith thisoption, the colormap isscaled to 8 bits. 

BUGS 

T he multi palette PC H G BigLinecnanges and H uffman decompression code are untested. 
REFERENCES 

Amiga ROM Kernel ReferenceM anual- Devices(3rd Ed.). Addison Wesley, ISBN 0-201-56775-X. 
SEEALSO 

ppm(5), ppmtoilbm(l) 

AUTHORS 

Copyright© 1989 byjef Poskanzer. 

M Odified October 1993 by Ingo W ilken (lngo.Wilken(ainformatik.uni-oldenburg.de) 

4 October 1993 



imake 

imake— C preprocessor interface to themake utility 
SYNOPSIS 



imake [ -Dd e f i n e ] [ — I d i r ] [ -Tt e mp I a t e ] [ -f f il e n a me ] [ -C fi I e n a me ] [ -s f i I e n a me ] 
[-e ][-v ] 



D ESC RIFIO N 

imake isused to generate Makefiies from atemplate a set of cpp macro functions, and a per-di rectory input file called an 
imakefiie. Thisallows machine dependencies (such ascompiler options, alternate command names, and special make rules) to 
be kept separate from the descri ptions of the various items to be bui It. 



imake 265 

OPTIONS 

T he followi ng command-lineoptions may be passed to imake: 

-Ddef i ne Thisoption ispassed directlyto cpp. It istypically used to set d i recto ry- spec i f i c vari ab I es. For example, the 

X W indow System usesthisflag to set topdir to thenameof the directory contai ni ng the top of the core 
distri bution and curdir to thenameof the current directory, relative to the top. 

-mi ree tory Thisoption ispassed directlyto cpp. It istypically used to indicate the directory in which the imake 
templateand confi guration filesmay befound. 

-Tt empi ate Thisoption specifies the name of the master template file (which is usuai ly located in the directory 
specified with -i) used by cpp. The default isimake.tmpi. 

-f f i i ename Thisoption specifies the name of the per-directory input fi le. The default isimakeme. 

-c fi i ename Thisoption specifies the name of the .c filethat isconstructed in the current directory. The default is 

Imakefile.c. 

-s f i i ename Thisoption specifies the name of themake descri ption fileto begenerated butmake should not beinvoked. 

If the menarne isa hyphen (-), the output iswritten to stdout. The default isto generate, but not execute, 

a Makef ile. 

-e Thisoption indicates the imake should execute the generated Makef ile. The default isto leavethisto the 

user. 

-v Thisoption indicates that imake should print the cpp command linethat it isusing to generate the 

Makef ile. 

HO W IT WORKS 

imake invokescpp with any-i or -d flags passed on the command li ne and passes the name of a fi le contai ning the followi ng 
three lines: 

#define IMAKE_TEMPLATE "Imake. tmpl" 
#define INCLUDEJMAKEFILE <Imakefile> 
#include IMAKE_TEMPLATE 

where imake. tmpi and imakefiie may beoverridden by the-T and -f command options, respecti vely. 

The imake_template typically readsin a fi le contai ning machine-dependent parameters (specified asepp symbols), a site 
specific parameters fi le, a file defini ng variables, a fi le contai ning cpp macro functions for generati ng make rules, and finally 
the imakefiie (specified by include_imakefile) in the current directory. The imakefiie uses the macro functions to indicate 
whattargets should be built; imake takes care of generati ng the appropri ate rules. 

imake configuration fi les contai n two typesof variables, imake variables and make variables. The imake variables are interpreted 
by cpp when imake isrun. By convention they aremixed case. The make variables are written into the Makef ile for later 
interpretation by make. By convention make variables are uppercase. 

The rules file (usually named imake. rules in the configuration directory) contai ns a variety of cpp macro functions that are 
confi gured accordi ngto the current platform. imake replacesany occurrencesof the stringe? with a newlineto allow macros 
that generate more than onelineof make rules. For example, when called with program_target(foo, fooi .0 f 002.0), the 
macro: 

#define program_target (program, objlist) @@\ 

program: objlist @@\ 

$(CC) -0 $@ Objlist $(LDFLAGS) 

will expand to 

foo: fool .0 foo2.o 

$(CC) -0 $@ fool.o foo2.o S(LDFLAGS) 



imake also repl aces any occurrences of the word xcomm with thecharacter # to permit placingcommentsin the Makef ile 
without causi ng invaiid directiveerrorsfrom the preprocessor. 
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Somecomplex imake macrosrequi re generateci make variables locai to each invocation of themacro, often becausetheir value 
dependson parameters passed to themacro. Such variables can becreated by usingan imake vari ableof the form xvARdefn, 
wheren is a single digit. A uni que make vari able wi 1 1 besubstituted. Later occurrencesof the vari ablexvARusen will bereplaced 
by the vari able created by the corresponding xvARdef n. 

On systems whosecpp reduces multiple tabs and spacesto a single space, ìmake attemptsto put back any necessary tabs(make 
isvery picky about thedifferencebetween tabs and spaces). For thisreason, colons(:) in command linesmust bepreceded 
by a backslash (\). 

USEWITHTH EX WIN DOW SYSTEM 

TheX Window System uses imake extensively, for bothfull bui Ids withi n thesourcetreeand external software. As men- 
tioned earlier, two special variables, topdir and curdir, are setto make referencingfiles usi ng relative pathnameseasier. For 
example, thefollowing command isgenerated automatically to build theniakeme in the directory iib/x/ (relative to the top 
of thesources): 

% ../../. /conf ig/imake -I ../../. /config \ 
-DTOPDIR=../. ./. -DCURDIR=./lib/X 

When buildingX programsoutsidethesourcetree, aspecial symbol useinstaiied isdefined and topdir and curdir are 
omitted. If the configurati on files havebeen properly installed, the seri ptxmkmf(l) may beused. 

INPUT FI LES 

H ereisasummary of the files read by imake asused by X. The indentati on showswhich files include which other files. 

Imake. tmpl generic variables 

site.def site -specific, Bef oreVendorCF defined 

.cf machine-specific 

Lib.rules shared library rules 

site.def site-specific, AfterVendorCF defined 

Imake. rules rules 

Project. tmpl X-specific variables 

Lib.tmpl shared library variables 

Imakefile 

Library. tmpl library rules 
Server. tmpl server rules 
Threads.tmpl multi-threaded rules 

N otethat site.def isincluded twice, oncebeforethe*.cf fileand onceafter. Although mostsitecustomizationsshould be 
specified after the*. cf file some, such asthechoiceof compiler, need to bespecified before, because other vari able setti ngs 
may depend on them. 

Thefirst ti me site.def isincluded, the vari able Bef oreVendorCF isdefined, and thesecond ti me, thevariableAftervendorCF is 
defined. Ali code in site.def should be inside a #ifdef for oneof thesesymbols. 

FILES 

imakefile. c Temporary input filefor epp 

/tmp/imf .xxxxxx Temporary Makef ne for -s 

/tmp/iif .xxxxxx Temporary imakefile if specified imakefile uses# comments 

/iib/cpp D efault C preprocessor 

SEEALSO 

make(l), xmkmf(l) 

S. I. Feldman, M ake- A Program for M aintaining Computer Programs 




EN VIRO NMENT VARIABLES 

Thefollowing environment variables may beset; however, their use is not recommended asthey introduce dependenciesthat 
arenot readily apparentwhen imake isrun. 

imakeinclude If defined, thi s should beavalid includeargumentfortheC preprocessor. Example 

-I/usr/include/local 

Actually, any valid cpp argumentwill work here. 
imakecpp If defined, thisshould beavalid path to a preprocessor program. Example 

/usr/local/cpp 

By default, imake Will USe /lib/cpp. 

imakemake If defined, thisshould beavalid path to a makeprogram, such as 

/usr/local/make 

By default, imake will usewhatever make program isfound usingexecvp(3). This variable isonly used if the 
-e option isspecified. 

AUTHORS 

Todd Brunhoff, Tektronix and M IT Project Athena 
Jim Fulton, M IT X Consortium 

X Versi on 11 Re!ease6 



imgtoppm 

imgtoppm— C onvert an img-wnatnot file into a portable pixmap 
SYNOPSIS 

imgtoppm [imgfile] 

DESCRIPTION 

imgtoppm readsan img-whatnot file as input and produces a portable pixmap as output. Theimg-whatnot toolkit isavailablefor 
FTP on venera.isi.edu, alongwith numerous images in thisformat. 

SEEALSO 

ppm(5) 

AUTHOR 

Based on asimpleconversion program posted to comp. graphics by Ed Falk. 
Copyright© 1989 by J ef Poskanzer. 

5 September 1989 

inews 

inews— Send a U senet arti de to the locai news server for distribution 



SYNOPSIS 

inews [ -h ][-D ][-0 ][-R ][-S ][header_flags ] [ i n p u t ] 
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mews reads a U senet news arti de (perhapswith headers) from thenamed file or standard input if no fileisgiven. It adds 
some headers and performssomeconsistency checks. If the article does not meet these checks (for example too much 
quotingof old articles, or postingto nonexistent newsgroups), then the article isrejected. If it passes the checks, inews sends 
the article to the locai news server asspecified in theinn.conf(5) file for di stributi on. 

In the standard modeof operation, the input consistsof the article headers, a blank line, and themessage body. For com- 
pati bility with older software, the-h flag must beused. If thereareno headers in themessage, then thisflag may beomitted. 

Several headers may bespecified on thecommand line, shown in thesynopsisaboveasheader flags. Each of these fi agstakes 
asingleparameter; if the valueis more than oneword (for example, almost ali Subject lines) then quotes must beused to 
preventtheshell from splitting it into multi pie words. The options, and their equi valent headers, areasfollows: 



a 


Approved 


c 


Control 


d 


D istribution 


e 


Expires 


f 


From 


w 


Followup-To 


n 


N ewsgroups 


r 


Reply-To 


t 


Subject 


F 


References 


0 


Organization 


X 


Path prefix 



ThePath header isbuilt accordi ngto thefollowing rules. If the- x flag isused, then itsvaluewill be the start of theheader. 
Any other host wi II see the site in theheader, and thereforenot offer the arti eie to that site If thepathhost configuration 
parameter is specifi ed in theinn.conf(5) file, then itwill beadded to thePath. Otherwise, if the server configuration 
parameter is specifi ed, then thefull domain nameof the locai host wi II beadded to thePath. ThePath will alwaysend 

not-for-mail. 

The default 0 rganization header will be provi ded if noneispresent in the article or if the -o flag isnotused. To prevent 
adding the default, use the -o flag. 

As a debugging aide, if the -d flag isused, the consistency checks will beperformed, and the article will besenttothe 
standard output, rather then sent to the server. 

For com pati bility with C News, inews accepts, but ignores, the -a, -v, and -w flags. The C N ews-N flag istreated as the -d flag. 

If afilenamed .signature existsin the user's home directory, inews will try to append itto the end of the article. If the fi le 
cannot beread, or if it istoo long (for example, more than four lines or one standard I/O buffer), or if some other problem 
occurs, then the article will not beposted. To suppressthis action, use the -s flag. 

I f the -r flag isused then inews will rejectanyattemptsto post control messages. 

If an unapproved posti ng ismadeto amoderated newsgroup, inews will try to mail the article to the moderator for posti ng. 
It usesthemoderators(5) fileto determi ne the mailing address. If no addressisfound, itwill usetheinn.cont fileto 
determine a "last-chance" hostto try. 

If the N NTP server needsto aumentiate the client, inews will usetheNNTPsendpass-word(3) routineto authenticateitself. In 
order to do this, the program will need read access to thepasswd.nntp(5) file. T his i s typi cally doneby having the file group- 
readableand making inews run setgid to thatgroup. 

mews exitswith azero status if the article wassuccessfully posted or mailed, or with a nonzero status if the article could not 
be delivered. 




info , 269 

Sinceinews will spool its input if the server isunavailable, it is usuai ly necessary to run rnews(l) with the-u flag on a regular 
basis, usually out of cron(8). 

HI STORY 

Written by Ri eh $alz (rsaizuuunet.uu.net) for I nterN etN ews 
SEEALSO 

moderators(5), inn.conf(5). rnews(l) 



info 



info— G N U 's hypertext system 
SYNOPSIS 

info [ - -option-name option-value ] enu-item... 

D ESC RIFIO N 

TheGN U project has a hypertext system called info that allowsthesamesourcefileto beeither printed asa paper manual, 
or viewed using info. It ispossibleto usetheinfo program from insideEmacs, orto usethestandaloneversion described 
here This manual pagegivesa brief summary of itscapabilities. 

OPTIONS 

--directory directory-path Add di rectory-path to the list of directory paths searched when info needsto find a file. 

You may issue - -directory multi pie ti mes. Alternati vely, you may specify a valueforthe 
environment variableiNFOPATH; if - -directory isnotgiven, thevalueof infopath isused. 
The value of infopath isacolon-separated I ist of directory names. If you do not supply 
ether infopath or -di rectory-path, info usesa default patti. 

-f menarne Specify a parti cular info fileto visit. By default, info visits the fi le dir; if you usethis 

option, info will start with (filename)top as the first fi le and node 

-n nodename Specify a particular nodeto visit in the initial filethat info loads. Thisisespecially useful in 

conjunction with - -file. You may specify - -node multiple ti mes. 

-o file D irect output to file instead of starti ngan interacti ve info session. 

-h Produce a relati vely brief description of the available info options. 

--version P ri nt the version information of info and exit. 

menu-item info treats its remaining arguments as the names of menu items. The first argument isa 

menu item in theinitial node visited, whilethesecond argument isa menu item in the first 
argument'snode You can easily movete the node of your choiceby specifying the menu 
names that describe the path to that node For example, info emacs buffers first selects the 
menu item emacs in the node (dir)Top, and then selects the menu item buffers in the node 

(emacs)Top. 

COMMANDS 

In info, thefollowing commands are available: 

b Invoketheinfotutorial. 

? Get a short summary of info commands. 

b Sdecttheinfo node from themain directory; this ismuch morecompletethan just using?. 

etn-g Abortwhateveryou aredoing. 
ctn-i Redraw thescreen. 
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n Movete the nextnodeof thisnode. 

p M ovete the previousnodeof thisnode. 

u M ovete thisnode'sup node. 

m Pick a menu item specified by name. Pickinga menu item causesanother nodeto beselected. You do not need to 

type a complete nodename; if you typeafew lettersand then a space or tab, info will try to fili in therest of the 
nodename. If you askforfurther completion without typing any morecharacters, you'll begiven a list of 
possi bili ti es; you can also get the list with ?. If you typeafew characters and then hit Enter, info will try to do a 
completion, and if it isambiguous, usethefirst possibility. 

f Follow a cross reference. You areasked for the name of the reference, usi ng command completion asform. 

1 Movete the last node you wereat. 

M ovingwithin a node 

space Serali forward a page. 

del Serali backward a page. 

b Gotothebeginningofthisnode. 

Advanced commands: 

q Quitinfo. 

1 Pick first item in node's menu. 

2-5 Pick second to fifth item in node's menu. 

g M ovete node specified by name You may includeafilenameaswell, as (filenamejnodename. 

s Search through this info fi le for a specified stri ng, and select the node in which thenext occurrenceis 

found. 



m-x print-node Pipe the contents of the current nodethrough thecommand in theenvironment variable 
info_print_command. I f the vari able does not exist, the node issimply piped to ipr. 

ENVIRONMENT 

infopath A colon-separated list ofdirectoriesto search for info files. Used if --directory isnotgiven. 

info_print_command Thecommand used forprinting. 

SEE ALSO 

emacs(l) 

AUTHOR 

Brian Fox, Free Software Foundation (bfox9ai.mit.edu) 
MANUAL AUTHOR 

Robert Lupton (rhl@astro.princeton.edu); updated by Robert J. Chassell (bob?gnu. ai. mit.edu). 

7 Decemberl990 

innconfval 

innconfvai— Get an I nterN etN ews confi guration parameter 
SYNOPSIS 

innconfval [ -f ] [par a me t er . . . ] 



insmod 
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mnconfvai pri nts the values of the parameters specified on thecommand line. Valuesare retri eved from theinn.conf(5) file 
and are descri bed there. 

Values are retrieved by usingtheGetconfigvaiue routine, orGetFiieConfigvaiue if the-f flag isused. Both aredescribed in 

libinn(3). 

HI STORY 

Written by Ri eh $alz (rsaizeuunet.uu.net) for InterNetNews 
SEEALSO 

libinn(3), inn.conf(5) 

insmod 

insmod— Instali loadable modules (aout and elf format) 
SYNOPSIS 

insmod [ -fkmsxv ] [ -o internal_name ] object_file [ symbol=value ... ] 

DESCRIPTION 

insmod installs a loadable module in the kernel. 

insmod triesto load a module into the kernel, and resolves ali symbolsfrom theexported kernel symbols, with version 
information, if available The module wi II get itsnameby removi ng the .0 extension from thebasenameof the object file. If 
the .0 extension isomitted, insmod wi 1 1 attemptto locate the module in somecommon default di rectories. If theenviron- 
ment contai ns the vari ableMODPATH, whereall d i recto ri es are separated with :, insmod will look in these di rectories for the 
module in the specified order. 

It ispossibleto load unversioned modulesin aversioned kernel, and ali combi nati onsof these. 
It isalso possi bleto load ELF modulesinto an a.out kernel, and ali combi nationsof these. 

It ispossibleto stack modules, that is, letone module use a previously loaded module. Ali modules that are referenced are 
updated with this reference Thisensuresthat a module can't beunloaded if there isanother module that refersto it. 

It ispossibleto changeinteger values in the module when loading it. Thismakesit possi bleto tune the module. 

The opti ons are as follows: 

-t The-t option triesto load the module even if the kernel or symbol versi ons differs from the 

version expected by the module. A warning will beissued if the module islocked to a 
specific kernel version that differs from the current version. 

-k Thisoption should really only beused by modprobe, to indicatethat the module insertion 

wasrequested by kerneid. Ali modules inserted usi ng this option will besubjectto 
autoremoval by the kerneid utility if they havebeen unused for more that a minute. (The 
usagecount iszero and no modules depend on this module.) If the kernel isnot kerneid- 
aware, themodulewill berejected by the kernel. Just load itwithoutthe -k option, and ali 
should bewell. 

-m The-m option will make insmod output a load map, that will makeit easier to debug your 

modules after a kernel panie, thanksto D erek Atkins(wariord@MiT.EDu). 

-0 The-o option allows the module to benamed to an explicit nameinstead of having a name 

derived from the name of the object fi le. N ote that this option can also beplaced after the 
modulename, so thatthesyntax of insmod looksmoresimilar to id. 
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symboi=vaiue[ .vaine] ... Thevalues of ali i nteger or character pointer symbolsin themodulecan bechanged at load- 
timeby naming a symbol and giving thenew value(s). If the symbol isdefined asan array of 
integersor character pointers, theelementsin the array can beinitialized by giving the 
valuesseparated by commas. Specific array entri es can beskipped by orni tting the value, as 
in symboi=vai uei,, vai u e 2 . Each i nteger value can begiven asadecimal, octal, orhexadeci- 
mal value: 17, 021, or 0x11. If the first character in the given value isnonnumeric, the value 
isinterpreted as a stri ng. The symbol isassumed to bea character pointer, which will be 
initialized to point to the stri ng. Extra space in the module will be allocateci for the stri ng 
itself. N otethesyntax: no spacesareallowed around the = or , signs! 

-s With thisoption, insmod will produce debugging i nformation and errar messagesusing the 

sysiog facility. (Al so used by kerneid, if you have installed it.) 

-v If you want verbose i nformation from theloading, select thisoption. 

-x Theno-exportflag, which will inhi bit the default insmod behavi or— inserti ng ali the 

module'sexternal symbolsinto the kernel symbol table. N otethat the kernel will stili 
update the referencesthat the module makesto previously loaded modules 

SEEALSO 

rmmod(l), modprobe(l), depmod(l), lsmod(l), ksyms(l), modules(2), genksyms(8) 

HISTORY 

The module supportwas fi rstconceived byAnonymous (asfar asl know). Linux version by BasLaarhoven (basevimec.m). 
0.99.14 version byjon Tombs(jon@gtex02. us.es). Extended by Bjom Ekwall (bj0m@biox.se). ELF hdpfrom Eric 

Youngdale (ericgaib.com). 

BUGS 

insmod relies on the "fact" that symbols, for which onewantsto change the value, aredefined as integersor character 

pointers, and that sizeof(int) == sizeof(char *). 

Linux, 14 May 1995 

instali 

instali— Copy fi les and set their attributes; GNU fileinstaller 
SYNOPSIS 

instali [options] [-s] [--strip] source dest 
instali [options] [-s] [--strip] source... directory 
instali [options] [-d, - -directory] directory... 

Options: 

[-c] [-ggroup] [-mmode] [-0 owner ] [ - -group=g r 0 u p ] [ - -mode=mode ] 
[ - -owner=owner ] [--help] [--version] 
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Thismanual page documents the GN U version of instali, instali copi es fi les and setstheir permission modesand, if 
possi ble, their owner and group. Used si mi lady to cp: typically used in Maketiies to copy programsinto their desti nati on 
directori es. Itcan also beused to create the desti nation directories and any leading directories, andto set thefinal di rectory's 
modes. It refusesto copy filesonto themselves. 



installit 




OPTIONS 

-c 

-d, --directory 



-g, - -group gr o u p 
-m, - -mode mode 

-o, - -owner owner 

-s, --strip 
- -help 
- -version 



installit 

instaiiit— File/directory i nstal lation tool 
SYNOPSIS 

installit [ -o owner ][-g group ][-0 owner ][-G gronp ][-m mode ][-b backup ] 
[-s ][-t ] source destination 
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installit putS a Copy Of source i ntO the Specifi ed destination. 

If source i s a peri od, then destination istaken to be the nameof a directory that should becreated. Otherwise, source is 
taken to namean existing file and dest i nati on may beeither a file or directory; it is i nterpreted accordi ng to thesamerules 
ascp(l). 

If desti nat i on namesa preexisting file, it will beremoved before the copy isdone. To make a backup copy, use the -b flag; 
the exi sci ng fi le wi 1 1 berenamed to havethespecified extension. If source and dest i nati on are the same stri ng, or if thetwo 
filesareidentical, then no copying isdone, and only the-o, -g, -m, and -s flagsareprocessed. In thiscase, the modification 
timeon the desti nati on will beupdated usingtoucn(l) unlessthe-n (don't touch) flag isused. 

After the desti nat i on has been created, it is possi bleto set the owner, group, and mode that it should have. T hi s isdone by 
usi ng the-o, -g, and -mflags, respectively. The-o and -g flags set the owner and group only if installit isbeing run by root, 
asdetermined bywnoami(l). To strip(l) an installed executable, usethe-s flag. 

N otethat installit usesno special privilegesto copy filesfrom one place to another. 

BUG SANO LIMITATIONS 

F I ags can n ot be com bi ned . 

Thechown(8) command must exist in either the /etc or /usr/etc directory or theuser'sPATH. 
Thewnoami command must exist in the /usr/ucb directory ortheuser's path. 



Ignored; for com pati bility with old U N IX versions of instali. 

Create each given directory and itsleading directories, if they do not already exist. Set theowner, 
group, and mode as given on the command line or to the defaults. Also givesany leading directories 
that are created thoseattributes. T his is different from theSunOS4.x instali, which gives 
directories that it creates the default attri butes 

Set the group ownership of the installed file or directory to the group ID of group (default is 
process's current group). group may also bea numeric group ID . 

Set the permi ssion mode for the installed fi le or directory to mode, which can beeither an octal 
number, or a symbol ic mode as in cnmod, with 0 asthepoint of departure. The default modeis 

0755. 

If run asroot, set the ownership of the installed fileto the user I D of owner (default is root). owner 

may also be a numeric user I D . 

Strip the symbol tablesfrom installed programs. 

Printausagemessageon standard output and exit successfully. 

Print version information on standard output and exit successfully. 

GNU FileU tilities 
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HISTORY 

W ritten by Ri eh $alz (rsaizguunet.uu.net) for InterN etN ews 

ispell, buildhash, munchlist, f indaf f ix, tryaf f ix, icombine, 
ijoin 

ispell, buildhash, munchlist, findaffix, tryaffix, icombine, ijoin --I nteracti ve Speli ing Checking 

SYNOPSIS 

ispell [ c o mmo n-flags ][-M|-N][-Lcontext ] [-V] files 

ispell [co mmo n-flags] -1 

ispell [common- fi ags ] [-f file] [ -s ] -a | -A 

ispell [-d file] [-w char s ] -c 

ispell [-d f il e ] [-w char s ] -e[e] 

ispell [-d file] -D 

ispell -v[v] 

common -flags: [-t][-n] [-b] [-x] [-B] [-C] [-P] [-m] [-S] [-d f i I e ] [ — p f i I e ][-w chars ] 
[-W n ] [-T t ype ] 

buildhash [-s] dict-file affix-file hash-file 

buildhash -s count af f ix -file munchlist [-1 aff-fi I e][ — c conv-fi le] 

[-T s u f f i x ] [ -s hash-file] [-D][-v][-w c ha r s ] [f i I es ] findaffix [ -p | -s] [ -f ] [ -c ] 

[-m mi n ] [ -M max ] [-e el i m] [-t tabehar ][-l I ow] [f i I es ] 

tryaffix [ -p j -s ] [-c] expanded-file af f i x [+add i t i on ] 

icombine [-T t y pe ] [af f • f i I e ] 

ijoin [ -s | -u ] join-options filel f i I e 2 
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ispeii isfashioned after the speli program from ITS (called ispeii on Twenexsystems.) Themost common usageisispeii 
menarne. In thiscase, ispeii will display each word which doesnot appear in the dictionary at the top of thescreen and 
allow you to change it. If there are "near misses" i n the dictionary (words that differ by only a single letter, a missing or extra 
letter, a pair of transposed letters, or a missing space or hyphen), then they arealso displayed on following lines. Aswell as 
near misses, ispeii may display other guessesat waysto make the word from aknown root, with each guess preceded by 
question marks. Finally, the li ne contai ni ng the word and theprevious lineareprinted at thebottom of thescreen. If your 
terminal can display in reverse video, the word itself ishighlighted. You havetheoption of replacing the word completely or 
choosing one of the suggested words. C ommands are si ngle characters as follows (case is ignored): 



r Replacethe misspelled word completely. 

Space Accepttheword thistimeonly. 

a Accepttheword fortherest ofthisispeii session. 

i Accepttheword, capitalized asit is in the file, and updateprivate dictionary. 

u Accepttheword, and add an uncapitalized (actually, ali lowercase) versi on to the private dictionary. 

e-n Replacewith one of the suggested words. 

l Look up words in system dictionary (controlied by thewoRDs compilation option). 

x W rite the rest of this fi le, ignori ng misspellings, and start next fi le. 

q Exit immediately and leavethefileunchanged. 

! Shell escape. 



i speli, buildhash, munchlist, findaffix, tryaffix, icombine, ijoin 



'L 



"Z 



Redraw screen. 
Suspend ispeii. 
Givehelp screen. 



If the-M switch isspecified, a one-line mini-menu atthebottom of thescreen will summarizetheseoptions. Conversely, the 
-N switch may beused to suppress the mini-menu. (The mini-menu isdisplayed by default if ispeii wascompiled with the 
minimenu option, butthesetwo switcheswill alwaysoverri de the default.) 

If the-L flag isgiven, the specified number isused asthenumber of linesof context to beshown atthebottom of thescreen. 
(The default isto calculatetheamount of context asacertain percentage of the screen size) Theamount of context issubject 
to a system- imposed limit. 

If the -v flag isgiven, charactersthat arenot in the 7-bit AN SI printablecharacter set will alwaysbedisplayed in thestyleof 
cat -v, even if ispeii thinksthat thesecharacters are legai ISO Latin-1 on your system. T hi s isuseful when working with 
older termi nals. W ithout this switch, ispeii will display 8-bit charactersas isif they havebeen defined asstring characters for 
thechosen filetype. 

Besidesthe-i, -a, and -Aoptions, N ormai mode accepts the following common flagson thecommand line: 
-t Theinputfileisin TeX orLaTeX format, 
-n Theinputfileisin nroff/troff format. 

-b C reate a backup f i le by appendi ng . bak to the name of the i nput fi le. 
-x Don'tcreateabackupfile. 

-b Report run-togetherwordswith missing blanks as speli ing errors. 

-c C onsider run-together words as legai compounds 

-p Don't generate extra root/affix combinations. 

-m M akepossibleroot/affixcombinationsthataren't in the dictionary. 

-s Sort the list of guesses by probable correctness. 

-d file Specifyan alternate dictionary file. For example, use -d deutsch to chooseaGerman dictionary in aGerman 
installati on. 

-p f i i e Specify an alternate personal dictionary. 

-w chars Specify additi onal charactersthat can be part of a word. 

-w n Specify length of words that are always legai. 

-t type Assume a givenformattertype for ali files. 

The-n and -t optionsselect whether ispeii runs in nroff/troff (-n) orTeX/LaTeX (-t) input mode. (The default is 
controlied by the deftexflag installation option.) TeX/LaTeX modeisalso automati cally selected if an input file has the 
extension .tex, unlessoverridden by the-n switch. In TeX/LaTeX mode, whenever a backslash (\) isfound, ispeii skips to 
thenextwhitespaceorTeX/LaTeX delimiter. Certain commandscontain argumentsthat should not bechecked, such as 
labelsand referencekeysfound in the \cite command, becausethey contai n arbitrary, nonword arguments. Speli checking is 
also suppressed when in math mode. Thus, for example, given 

\chapter {This is a Ckapter} \cite{SCH86} 

ispeii will find "ckapter" but not "sch." T he -t option does not recognizetheTeX comment character%, so commentsare 
also speli checked. It also assumescorrect LaTeX syntax. Arguments to infrequently used commandsand someoptional 
arguments are sometimes checked unnecessari ly. T he bibliography wi II not be checked if ispeii was compiled with ignorebib 
defined. Otherwise, the bibliography will bechecked but the referencekey will not. 

Referencesforthetib(l) bibliography system (textbetween a[. or<. and .] or .>) will always bei gnored inTeX/LaTeX mode. 

The-b and -x options control whether ispeii leaves a backup (.bak) fi le for each input file. 

The .bak fi le contai ns the precorrected text. If there are file opening/wri ti ng errors, the .bak fi le may beleftfor recovery 
purposeseven with the-x option. The default for this option is controlied by the defnobackupflag installation option. 
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The-B and -c options control how ispeii handles run-togetherwords, such asnotthefor not the I f -b isspecified, such 
words will beconsidered errors, and ispeii will list variati onswith an inserted blank or hyphen as possi ble replacements. If 
-c isspecified, run-togetherwords will beconsidered to be legai compounds, so longasboth componentsarein the 
dictionary, and each component isat least aslongasa language-dependent minimum (threecharacters, by default). Thisis 
useful for languagessuch asGerman and Norwegian, where many compound words areformed by concatenation. (Notethat 
compounds formed from threeor more root words will stili beconsidered errors). The default for thisoption is language- 
dependent; in a multi linguai installation, the default may vary dependi ng on which dictionary you choose. 

The-p and -m options control when ispeii automatically generatessuggested root/affix combinationsfor possi ble addition to 
your personal dictionary. (T hese are the entri es in the"guess" list that are preceded by question marks.) If -p isspecified, 
such guessesaredisplayed only if ispeii cannot generate any possibi lities that match thecurrent dictionary. If -m isspecified, 
such guessesarealwaysdisplayed. Thiscan be useful if the dictionary hasa limited word list, or a word list with few suffixes. 
H owever, you should becareful when usi ng thisoption, asit can generate guesses that produce il legai words. The default for 
thisoption is controlied by thedictionary fileused. 

T he -s option suppresses ispeii's normal behavior of sorting the list of possible replacement words. Some people may prefer 
this, sinceit somewhat enhances the probability that the correct word will below-numbered. 

The-d option isused to specify an alternate hashed dictionary file, otherthan the default. If the filmarne does not contai n a 
/, the library directory for the default dictionary file isprefixed; thus, to use a dictionary in the locai directory -d ./xxx.hash 
must beused. Thisis useful to allow dictionaries for alternate languages. Unlike previ ousversionsof ispeii, a dictionary of 
/dev/nuii isillegal because the dictionary contai ns the affixtable. If you need an effectively empty dictionary, createaone- 
entry list with an unlikely string (for example, "qqqqq"). 

The-p option isused to specify an alternate personal dictionary file. If the filmarne does not begin with /, $home isprefixed. 
Also, the shell variablewoRDLisT may beset, which renames the personal dictionary in thesamemanner. Thecommand line 
overridesanywoRDLisT setting. If neither the-p switch northewoRDLisT environmmtvariableisgiven, ispeii will search fora 
personal dictionary in both thecurrmt directory and $home, creati ng onein $home if none isfound. The preferred nameis 
constructed by appending .ispeii to the base nameof the hash file. For example, if you usethe English dictionary, your 
personal dictionary would benamed .ispeii_engiish. However, if the file .ispeii_words exists, itwill beused as the personal 
dictionary regardlessof the language hash filechosen. Thisfeatureisincluded pri mari ly for backwards compati bility. 

If the-p option isnot specified, ispeii will look for personal dictionaries in both thecurrent directory and the home 
directory. If dictionaries exist in both places, they will bemerged. When words are added to the personal dictionary, they will 
bewritten to thecurrent directory if a dictionary already existed in that place; otherwise, they will bewritten to the 
dictionary in the home directory. 

T he -w option may beused to specify eh aracters otherthan alphabeticsthat may also appear i n words. For instance, -w "&" 
will allow "AT&T" to bepicked up. U nderscores are useful in many technical docummts. Thereisan admittedly crude 
provision in thisoption for 8-bit international characters. N onprintingcharactersmay be specified in the usuai way by 
inserting a backslash followed by the octal character code, for example, \014for aform feed. Alternati vely, if n appearsin the 
character string, the(up to) three characters following are a decimai code, 0-255, for the character. For example, to include 
bel Is and form feeds in your words (an admittedly si lly thingto do, but aren't most pedagogical examples): 

n007n012 

N umeric digits otherthan the three following n aresimply numeric characters. Useof n does not confliet with anything 
because actual alphabetics haveno meaning; alphabetics are already accepted. ispeii will typically beused with input from a 
file, meaning that preservi ng parity for possi ble 8-bit characters from the input text isokay. If you specify the -1 option, and 
actually typetext from the terminal, this may create problemsif your stty setti ngs preserve parity. 

The -w option may beused to changethelmgth of words that ispeii alwaysacceptsas legai. N ormai ly, ispeii will accept ali 
one-character words as legai, which isequivalent to specifying-w 1. (The default for this switch is actually controlied by the 
minword installation option, so it may vary at your installation.) If you want ali words to bechecked against the dictionary, 
regardlessof Imgth, you might want to specify -w 0. On theother hand, if your document specifiesto accept ali words of 
three letters or less, then regardlessof the setti ngof thisoption, ispeii will only gmerate words that are in thedictionary as 
suggested replacemmts for words; this prevents the list from becomingtoo long. Obviously, thisoption can bevery 
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dangerous, since short misspellings may bemissed. If you usethisoption a lot, you should probably makea last passwithout 
it beforeyou publish your documenti, to protect yourself against errors 

The-T option isused to specify a default formattertypefor use in generati ng stringcharacters. Thisswitch overridesthe 
default type determi ned from thefilename. Thetype argument may beeither oneof theuniquenamesdefined in the 
language affix fi le (such asnroff) or a fi le suffix includi ng the dot (for example, .tex). If no -t option appearsand no type 
can bedetermined from the fi lename, the default string character type declared in the language affix file wi II beused. 

The-i or list option to ispeii isused to produce a list of misspelled wordsfrom the standard input. 

The -a option isintended to beused from other programsthrough a pipe. In thismode, ispeii printsa one-line version 
identification message, and then beginsreading linesof input. For each input line, a single line iswritten to thestandard 
output for each word checked for speli ing on the line. If the word wasfound in the mai n dictionary, or your personal 
dictionary, then the li ne contai nsonly a*. If the word wasfound through affix removal, then the li ne contai ns a +, a space, 
and the root word. If theword wasfound through compound formation (concatenation of two words, controlied by the-c 
option), then the li ne contai nsonly a-. 

If theword isnot in the dictionary, but therearenear misses, then the line contai nsan &, a space, the misspelled word, a 
space, thenumber of near misses, thenumber of characters between thebeginningof the li ne and thebeginningof the 
misspelled word, a colon, another space, and a list of the near missesseparated by commasand spaces. Following the near 
misses (and identified only by thecount of near misses), if theword could beformed by adding (il legai) affixesto a known 
root, isa list of suggested derivations, again separated by commasand spaces. If there are no near misses at ali, the line format 
isthesame, except that the & is replaced by ? (and thenear-misscount isalways zero). The suggested derivationsfollowing 
the near misses are in theform: 

[ p r e f i x + ] root [-prefix] [-suffix] [+suffix] 

(for example, "retfry-y-Hes" to get "refries") whereeach optional pfx and sfx isa string. Also, each near miss or guess is 
capital ized the sameas the input word unlesssuch capitalization is illegal; in the latter case each near miss i scapi tal ized 
correctly accordi ng to the dictionary. 

Finally, if theword does not appear in the dictionary, and there are no near misses, then the li ne contai ns a #, a space, the 
misspelled word, a space, and the character offset from thebeginningof the li ne Each sentenceof text input is termi nated 
with an additional blank line, indicating that ispeii hascompleted processing the input line. 

These output linescan besummarized asfollows: 

OK: 

Root: + <root> 
Compound: 

Miss: & <original><count><offset>: <miss>, <miss>, <guess>, ... 

GueSS: ? <original> 0 <offset>: <guess>, <guess>, ... 

N One # <original> <off set> 

For example, a dummy dictionary contai ni ng the words fray, Frey, fry, and refried might produce thefollowing responseto 

the COmmand echo 'frqy refries ] ispell -a -m -d . /test . flash : 

(#) International Ispell Version 3.0.05 (beta), 08/10/91 

& frqy 3 0: fray, Frey, fry 

& refries 1 5: refried, re+fry-y+ies 

Thismodeisalso suitableforinteractiveusewhen you wantto figure out the speli ingof a single word. 

The -a option worksjust like-a, except that if a line begins with the string "&inciude Fiiev, therest of the line istaken as 
thenameof afileto read for further words. Input returnsto the originai filewhen the include file isexhausted. Inclusion 
may benested up to fivedeep. Thekey string may bechanged with the envi ronment variable include_string (theamper- 
sands if any, must beincluded). 
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When in the -a mode, ispeii will also accept linesof single words prefixed with any of thefollowing: \ &, e, +, -, ", #, !, % 
or ". A li ne starti ng with * tells ispeii to insert the word into theuser'sdictionary (similar to the i command). A line 
starti ng with & tdlsispeii to insert an all-lowercaseversion of the word into theuser'sdictionary (similar to theu com- 
mand). A li ne starti ng with e causes ispeii to accept this word in the future (si mi larto the a command). A line starti ng with 
+, followed immedi ately by tex or nroff, will cause ispeii to parse future input accordi ng the syntaxof thatformatter. A line 
consisting solely of a + will place ispeii in TeX/LaTeX mode (similar to the-t option) and - returnsispeii to nroff/troff 
mode (butthese commands are obsolete). H owever, string character type is not changed; the " command must beused to do 
this. A li ne starti ng with ■ causes ispeii to set internai parameters (in particular, the default string character type) based on 
thefilenamegiven in therest of the line. (A file suffix issufficient, but the peri od must beincluded. Instead of afilenameor 
suffix, auniquename, as listed in thelanguageaffixfile, may bespecified.) H owever, theformatter parsi ng is not changed; 
the + command must beused to change theformatter. A line prefixed with # will cause the personal dictionary to besaved. A 
li ne prefixed with ! will turn on terse mode (explai ned later in thissubsection), and a line prefixed with % will return ispeii 
to normal (non-terse) mode. Any input following the prefix characters+, -, #, i, or% isignored, asisany input following the 
filenameon a " line. To allow speli checking of linesbeginning with thesecharacters, a line starti ng with " hasthat character 
removed beforeit ispassed to the speli checking code. It isrecommended that program matic interfaces prefix every data line 
with an up arrow to protect themselves against future changes in ispeii. 

To summarizethese 

Add to personal dictionary 
@ Accept word, but leaveoutof dictionary 

# Savecurrent personal dictionary 

Set param eters based o n f i I en am e 
+ EnterTeX mode 

ExitTeX mode 
! E n ter terse mode 

% Exit terse mode 

Speli check rest of line 

In terse mode, ispeii will not print linesbeginning with *, +, or-, ali of which indicate correct words. Thissignificantly 
improvesrunningspeed when the drivi ng program isgoingto ignore correct words anyway. 

The-s option isonly valid in conjunction with the -a or -a options, and only on BSD-derived systems. If specified, ispeii 
will stop itself with asiGTSTP signal after each I i ne of input. It will not read more input unti I it receivesasiGcoNT signal. This 
may beuseful for handshaking with certain text editors. 

The-f option isonly valid in conjunction with the -a or -a options. If -t is specified, ispeii will write its resultsto the 
given file, rather than to standard output. 

The-v option causes ispeii to print i ts cu rrent versi on identificati on on the standard output and exit. If theswitch is 
doubled, ispeii will also print the options that itwas compi led with. 

The-c, -e[i -4], and -d options ofispeii areprimarily intendedforusebythemuncmist shell script. The -c switch causesa 
list of words to beread from the standard input. For each word, a list of possi bleroot words and affixes wi II bewritten to the 
standard output. Some of the root words will bei Negai and must befiltered from the output by other means; themuncmist 
script does this. Asan example, thecommand 

echo BOTHER ] ispell -c 

produces 

BOTHER BOTHE/R BOTH/R 

The -e switch is the reverse of -c; it expandsaffixflagsto produce a list of words. For example, thecommand 

echo BOTH/R ] ispell -e 

produces 

BOTH BOTHER 
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An optional expansion level can also bespecified. A level of 1 (-ei) isthesameas-e alone. A level of 2 causes the originai 
root/affix combination to be prepended to the line: 

BOTH/R BOTH BOTHER 

A level of 3 causes multi pie li nesto be output, onefor each generated word, with the originai root/affix combination 
followed bytheword it createsi 

BOTH/R BOTH 
BOTH/R BOTHER 

A level of 4 causes a floating-point number to beappended to each of the level 3 lines, giving the ratio between thelength of 
the root and the total length of ali generated wordsincludingtheroot: 

BOTH/R BOTH 2.500000 
BOTH/R BOTHER 2.500000 

Finally, the -d flag causes the affixtablesfrom thedictionary fileto bedumped to standard output. 

Unlessyour system administrator hassuppressed thefeatureto save space, ispeii isawareof thecorrect capitalizationsof 
wordsin thedictionary and in your personal dictionary. Aswell asrecognizingwordsthat must be capital ized (such as 
George) and wordsthat must beali capi tals (such asN ASA), it can also handlewordswith unusual capitalization (for 
example, IT-CorporTeX ). If aword iscapitalized incorrectly, the I ist of possibilitieswill include ali acceptabl e capi tal i za- 
tions. (M orethan one capitalization may beacceptable; for example, my dictionary lists both IT Corp and ITcorp.) 

N ormally, thisfeaturewill not cause you surprises, but thereisonecircumstanceyou need to beawareof. If you usei to add 
aword to your dictionary that isat thebeginning of a sentence (for example, the first word of thisparagraph if normally were 
not in thedictionary), itwill bemarked as "capitalization required." A subsequentusageofthiswordwithout capitalization 
will beconsidered a misspelling by ispeii, and itwill suggest the capital ized version. You must then compare the actual 
spellingsby eye, and then typei to add theuncapitalized variantto your personal dictionary. You can avoid thisproblem by 
usingutoadd theoriginal word, ratherthan i. 

T h e ru I es f o r capi tal i zati on are as f o 1 1 ows: 

1. Any word may appear in ali capitals, as in headings. 

2. Any word that is in thedictionary in ali lowercaseform may appear either in lowercase or capitalized (asat the 
beginningof a sentence). 

3. Any word that has unusual capitalization (that is, it contai ns both casesand thereisan uppercasecharacter besidesthe 
first) must appear exactly as in thedictionary, except aspermitted by rule 1. If the word isacceptable in ali lowercase, it 
must appear thusin a dictionary entry. 

buildhash 

Thebuiidhash program buildshashed dictionary filesfor later use byispeii. The raw word I ist {with affixflags) isgiven in 
dict-me, and the affixflags are defi ned by affìx -file. The hashed output iswritten to hash -file. The formatsof the two 
input files are described in ispeii(4). The-s (silent) option suppresses the usuai status messages that are w ri tten to the 
standard error device. 

munchlist 

The munchlist shell script isused to reduce the sizeof dictionary files, primarily personal dictionary files. It is also capableof 
combini ng dictionaries from varioussources. Thegiven files areread (standard input if no argumentsaregiven), reduced to 
a minimal set of rootsand affi xes that will match the same list of words, and written to standard output. 

Input for munchlist contai nsof raw words (such asthosefrom your personal dictionary files) or root and affix combinations 
(probably generated in earlier munchlist runs). Each word or root/affix combination must beon a separate line. 

The-D (debug) option leaves tempo rary filesaround under standard namesinstead of deleti ngthem, so that the script can be 
debugged. W arni ng: This option can eat up an enormousamount of tempo rary file space. 

The-v (verbose) option causes progress messages to bereported to stderr so you won't get nervousthat munchlist hashung. 
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If the-s (strip) option is specifi ed, wordsthat are in the specified hash-me areremoved from the word list. Thiscan be 
useful with personal dictionaries. 

The-i can beused to specify an alternate affix -file for munching dictionaries in languagesother than English. 

The-c option can beused to convert dictionaries thatwere bui It with an older affix file, without risk of accidentali 
introduci ng unintended affix combinations into the dictionary. 

The-T option allows dictionaries to beconverted to a canoni cai string-character format. The suffix specifi ed islooked up in 
the affix fi le (-1 switch) to determ ine the string-character format used for the input file; the output alwaysusesthecanonical 
string-character format. For example, a dictionary collected fromTeX source fi lesmight beconverted to canonical format by 
specifying-T tex. 

The-w option ispassed on to ispeii. 
findaffix 

Thetindaffix shell script isan aid to writersof new language descri ptions in choosing affixes. Thegiven dictionary fi les 
(standard input if none are given) areexamined for possi bleprefixes(-p switch) or suffixes(-s switch, the default). Each 
commonly occurring affix ispresented along with a count of thenumber of times it appearsand an estimateof thenumber 
of bytes that would besaved in a dictionary hash file if it were added to the language table. Only affixes that generate legai 
roots(found in theoriginal input) are listed. 

If the -c option isnot given, theoutput linesarein thefollowing format: 

strip/ add/ count /bytes 

where strip is the stri ng that should be stri pped from a rootword beforeadding the affix, add istheaffixto be added, count 
is a count of thenumber of times that this strip/ add combination appears, and bytes isan estimateof thenumber of bytes 
that might besaved in theraw dictionary file if this combination is added to the affix f ile The fi eld separator in theoutput 
will bethetab character specified by the -t switch; the default isaslash (/). 

If the-c (clean output) option is given, the appearanceof theoutput ismadevisually cleaner (but harder to post process) by 
changing itto 

-strip+add<tab>count<tab>bytes 

where strip, add, count.and bytes areasbefore, and <tab> representstheASCII tab character. 

Themethod used to generate possi ble affixes will also generate longer affixes which have common headersortrailers. For 
example, thetwo wordsmoth and mother will generate not only the obvious substitution +er but also -h+her and -tn+ther 
(and possi bly even longer ones, dependi ng on thevalueof min). To prevent cluttering the output with such affixes, any affix 
pai r that shares a common header (or, for prefixes, trailer) stri ng longer than eiim characters (default 1) will besuppressed. 
You may wantto set eiim to a valuegreater than 1 if your language has stri ng characters; usually, theneed for this parameter 
will become obvious when you exami ne the output of your findaffix run. 

N ormally, the affixes are sorted accordi ng to the estimateof bytes saved. The -f switch may beused to cause the affi xesto be 
sorted by frequency of appearance. 

To save output fi le space, affixes which occurfewer than 10 times are eli mi nated; thislimit may bechanged with the-i 
switch. T he -m switch specifies a maximum affix length (default 8). Affixes longer than this will not bereported. (Thissaves 
on temporary disk space and makes the script run faster.) 

Affixes which generate stemsshorter than three characters are suppressed. (A stem istheword after thestrip string hasbeen 
removed, and beforetheadd string hasbeen added.) This reducesboth therunningtimeand the size of the output fi le. This 
limit may bechanged with the-m switch. The minimum stem length should only beset to 1 if you have a lot off ree ti me 
and disk space (in therange of many daysand hundredsof megabytes). 

Thetindaffix script requiresa nonblank field-separator character for internai use N ormally, this character isaslash (/), but 
if the slash appears as a character in the input word list, adifferent character can be specified with the-t switch. 

ispeii dictionaries should beexpanded before beingfed to findaffix; in addition, characters that are not in the English 
alphabet (if any) should betranslated to lowercase. 



i speli, bui Idhash, munchlist, findaffix, tryaffix, icombine, ijoin 



tryaffix 



The tryaffix shell script isused to estimatetheeffectivenessof a proposed prefix (-p switch) or suffix (-s switch, the default) 
with agiven expanded-me. 0 nly oneaffixcan betried with each execution of tryaffix, although multi pie argumentscan be 
used to describevaryingformsof thesameaffixflag(forexample, theD flagfor English can add either d or ed dependi ngon 
whether a trai li ng E isalready present). Each word in theexpanded dictionary that ends (or begins) with thechosen suffix (or 
prefix) hasthat suffix (prefix) removed; the dictionary isthen searched for rootwordsthat match thestripped word. Nor- 
mally, ali matching rootsarewritten to standard output, but if the-c (count) flag isgiven, only a statisti cai summary of the 
results iswritten. The stati sticsgiven area count ofwords the affix potenti ally appliesto and an estimate of the num ber of 
dictionary bytes that a flag usi ng the affix would save. The estimate wi II behigh if the flag generateswordsthat arecurrently 
generated by other affix flags (for exam pie, in English, bathers can begenerated by either bath/x or bather/s). The diction- 
ary file, expanded-fiie, must al ready beexpanded (usi ng the -e switch of ispeii) and sorted, and thingswill usually work 
best if uppercase has been folded to lower with tr. 

The affix argumentsarethingsto be stri pped from the dictionary file to produce tri al roots: for English, con (prefix) and ing 
(suffix) areexamples. Theaddition partsof the argument are lettere that would havebeen stripped off theroot before adding 
the affix. Forexample, in English the affix ing normally stri ps e forwordsending in that letter (for exam pie, me becomes 
ìiking), so wemight run 

tryaffix ing ing+e 

to cover both cases. 

Ali of the shell seri pts contai n documentation ascommentary atthebeginning; sometimesthesecommentscontain useful 
information beyond the scope of thismanual page. 

It ispossibleto instali ispeii in such away asto only support ASCII rangetext if desired. 
icombine 

The icombine program is a nel per for munchlist. It reads a list ofwords in dictionary format (roots plus flags) from the 
standard input, and produces a reduced listof standard output that combines common roots found on adjacent entri es. 
Identical roots that have differing flags will havetheir flags combined, and roots that havediffering capitalizationswill be 
combined in away that only preservesimportant capitalization information. The optional aff -file specifiesa languagefile 
that defines the character sets used and themeanings of the various flags. The -t switch can beused to sei ect among 
alternative string character types by giving a dummy suffix that can be found in an aitstringtype statement. 



The ijoin program is a reimplementati on of join(l), which handles long linesand 8-bit characters correctly. The-s switch 
specifiesthatthesort(l) program used to prepare the input to ijoin usessigned compari sonson 8-bit characters; the-u 
switch specifiesthatsort(l) usesunsigned comparisons. Ali other opti ons and behaviorsof join(l) areduplicated asexactly 
as possi blebased on themanual page, except that ijoin will not handle newline asa field separator. Seethe join(l) manual 
page for more information. 



i]0in 



ENVIRONMENT 



WORDLIST 



TMPDIR 



DICTIONARY 



INCLUDE_STRING 



Default dictionary to useif no -d flag isgiven 

Personal dictionary filename 

Code for fileinclusion under the -a option 

D irectory used for someof muncniist'stemporary files 



FILES 



/usr/dict/web2 Or /usr/dict/words 



.ispelljiashfile 



! ! LIBDIR ! ! / ! ! DEFHASH! ! 



! ! LIBDIR ! ! / ! ! DEFLANG! ! 



H ashed dictionary (may be found in someother locai directory, depending on the 
system) 

Affix-def i nition fi le for munchlist 

FortheLookup function (depending on thewoRDs compilation option) 

User's private dictionary 

D irectory-specific private dictionary 
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SEEALSO 

spell(l), egrep(l), look(l), join(l), sort(l), sq(lL), tib(lL), ispell(4L), english(4L) 

BUGS 

1 1 takes sazerai to many secondsfor ispeii to read in thehash table, dependingon size. 

When ali opti ons are enabled, ispeii may takeseveral secondsto generate ali theguessesat correctionsfor a misspelled word; 
on slower machinesthistimeislongenough to beannoying. 

Thehash table isstored as a quarter-megabyte (or larger) array, so a PDP-11 or 286 version does not seem likely. 
ispeii should understand moretroff syntax, and deal more intelligently with contractions. 

Although small personal dictionaries are sorteci beforethey arewritten out, theorderof capitalizationsof thesameword is 
somewhat random. 

Whenthe-x flag isspecified, ispeii will unlink any existing BAK file. 
Therearetoo many flags, and many of them havenon-mnemonic names. 

munchiist does not deal very gracefully with dictionaries that contain nonword characters. Such characters ought to be 
deleted from the dictionary with awarning message. findaffix and muncniist requiretremendousamountsof temporary file 
space for large dictionaries. They do respect the tmpdir environment variable, so this space can beredirected. H owever, a lot 
of thetemporary spaceneeded isforsorting, so tmpdir isonly a partial help on systemswith an uncooperativesort(l). 
(Cooperative isdefi ned asaccepting theundocumented -t switch). At itspeak usage, muncmist takes 10 to 40 timesthe 
originai dictionary'ssizein kilobytes. (The larger ratio i s for dictionaries that already haveheavy affixuse, such astheone 
distri buted with ispeii). muncmist isalso very slow; munchinga normal-sized dictionary (15KB roots, 45KB expanded 
words) takes around an hour on a small workstation. (M ost of this time is spent in sort(l), and muncniist can run much 
faster on machinesthat have a more modem sort that makes better useof thememory availableto it.) findaffix iseven 
worse; the smallest English dictionary cannot beprocessed with this script in a mere 50KB off ree space, and even after 
specifying switchesto reduce thetemporary space requi red, the script will run for more than 24 hourson a small worksta- 
tion. 

AUTHORS 

Pace Wi Ili sson (pace@mit-vax), 1983, based on thePDP-10 assembly version. That version waswritten by R. E. Gorin in 
1971, and later revised by W. E. M atson (1974) and W. B. Ackerman (1978). Collected, revised, and enhanced for the 
Usenet by Walt Buehring, 1987. Table-driven multilingual version by Geoff Kuenning, 1987-88. Large dictionaries 
provided by Bob Devi ne (vianet! devine). A complete list of contri butorsistoo largete list here, but is di stri buted with the 

ispell SOUrCS i n the fi le Contributors. 

VERSION 

The version of ispeii described by thismanual page is International Ispell version 3.1.00, October 8, 1993. 



join 

join— Join linesof two fileson a common field 
SYN0PSIS 

join [-a 1 J 2 ] [-v 1]2] [-e empty -string ] [-0 field-list. . . ] [-t char] 
[-j [1 12] field] [-1 field] [-2 field] f il el f i I e 2 
join {- -help, - -version} 

D ESC RIFI0 N 

Thismanual page documents the GN U version of join. join printsto the standard output a li ne for each pair of input lines, 
oneeach from mei and f i i e 2 , that haveidentical join fields. Either filename (but not both) can be-, meaning the standard 



input, f i i ei and fi i e 2 should beai ready sorted in increasing order (not numerically) on thejoin fields; unlessthe-t option 
isgiven, they should be sorted ignori ng blanksat the start of the line, assort doeswhen given the -b option. 

T he defaults are the following: Thejoin field isthefirst field in each line; fields in the input areseparated by oneormore 
blanks, with leading blankson thelineignored; fields in the output areseparated by a space; each output line consistsof the 
join field, the remai ni ng fields from fi lei, then the remaining fieldsfrom f i 1 e 2 . 

OPTIONS 

-a file-number 



Print a lineforeach unpai rable line in fileme-number (either 1 or 2), in addition to thenormal 
output. 

Replace empty output fields (thosethat are mi ssing in the input) with string. 
Join on field fieid (a positive integer) of filel. 
Join on field fieid (a positive integer) of fi le 2. 
Equivalentto -1 fieid -2 fieid. 

Construct each output li ne accordi ng to the format in fieid -list. Each dement in fieid -list 
consistsof a file number (either 1 or 2), a peri od, and a field number (a positive integer). The 
elementsin the list areseparated by commasor blanks. M ulti pie fieid -list argumentscan be 
given after a single -0 option; thevaluesof ali lists given with -0 areconcatenated together. 
Usecharacter cnar as the input and output field separator. 

Print a lineforeach unpai rable line in fi le file -number (either 1 or 2), instead of thenormal output. 
In addition, when GNU join isinvoked with exactly oneargument, the following options are recognized: 
-heip Printausagemessageon standard output and exitsuccessfully. 

--version Print version information on standard output, then exitsuccessfully. 

GNU TextUtilities 



-e string 
-1, -j1 field 
-2, -j2 field 
-j field 
-0 field-list. . 



-t char 

-v file-number 



kill 

km— Terminate a process 
SYNOPSIS 

kill [ -s signal ] -p ] [-a]pid ... 
kill -1 [ signal ] 

D ESC RIFIO N 

km sends the specified signal to the specified process. If no signal isspecified, theTERM signal issent. TheTERM signal will kill 
processesthat do not catch this signal. For other processes, if may be necessary to usetheKiLi_(9) signal becausethis signal 
cannot be caught. 

Most modem shells have a bui It-i n kill function. 
OPTIONS 

pid ... Specify the list of processes that kiii should signal. Eachpid can bea process ID, or a process name. 
-s Specify thesignal to send. The signal may be given asa signal nameornumber. 

-p Specify that km should only print the process ID (pid) of the named process, and should not send ita signal. 
-1 Print a list of signal names. Thesearefound in /usr/inciude/iinux/signai.h. 

SEEALSO 

bash(l), tcsh(l), kill(2), sigvec(2) 
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AUTHOR 

Taken from BSD 4.4. The abili tyto translate process namesto process idswasadded by Salvatore Val ente 

(<svalente@mit.edu>). 

Linux Utilities, 14 October 1994 

killall 

kiiiaii — K ili processes by name 
SYNOPSIS 

killall [-iv] [-si guai ] name ... 
killall [-1] 

D ESC RIFIO N 

kiiiaii sends a signal to ali processes runningany of thespecified commands. If no signal nameisspecified, sigterm issent. 

Signalscan bespecified either by name(for example, -hup) or by number (for example, -1). Signal a (check if a process exists) 
can only bespecified by number. 

If thecommand name contai ns a slash (/), processes executing that parti cular file wi II beselected for killing, independent of 
their name. 

kulan returns a nonzero return codeif no process has been killed forany of the I isted commands. If at least one process has 
been killed foreach command, kiiiaii returns zero. 

A kiiiaii process neverkillsitself(butmayki II other kulan processes). 
OPTIONS 

-i Interactively ask for confirmation of killing. 

-ì Listali known signal names. 

-v Report if thesignal wassuccessfully sent. 

FILES 

/proc Location oftheproc filesystem 
KNOWN BUGS 

Killing by fi le only works for executablesthat arekept open during execution; that is, impure executables can 't be killed this 
way. 

AUTHOR 

W erner Almesberger (aimesber@di . epf ì. eh) 
SEEALSO 

kill(l), fuser(l), ps(l), kill(2) 

Linux, 11 October 1994 

ksyms 

ksyms— Showstheexported kernel symbols 
SYNOPSIS 

ksyms [-a] [-h] [-m] 



lai 285 
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ksyms shows information aboutall exported kernel symbols. The format is 

a d d r e s s n a me [ d e f i ni n g modn I e ] 

The describing header can beturned off with theoption -h. 

N ormally, only the symbols defi ned by theloaded modulesareshown, but with theoption -a, ali exported symbols can be 
seen. 

The information can also beseen in /proc/ksyms. A shell-script version ksyms. sh can beused to get the information from / 
proc/ksyms instead, but this program gets the symbol information directly from the kernel with asystem cali. 

With theoption -m (standsfor memory map), you can also see the starti ng addressand thesizeof the allocateci memory for 
every loaded module. 

SEE ALSO 

insmod(l), modprobe(l), depmod(l), rmmod(l), lsmod(l), modules(2) 

HI STORY 

The ksyms command was first conceived by Bjorn Ekwall (bj0rn9biox.se). The -m option wasinspired by David H inds 

(dhinds@allegro . Stanford . edu) 

BUGS 

Ksyms might havesome, but they arewell hidden.... 

Linux, 14 May 1995 

last 

ìast— Indicate last logins by user or terminal 
SYNOPSIS 

last [ -n u mb e r ] [ -f fi I e n a me ] [ — t tty][-h hostname ] [-i address ][-l] [-y][name ...] 

D ESC RIFIO N 

Last looksback in thewtmp file, which records ali logins and logoutsfor information about a user, ateletype, or any group of 
usersand tei etypes. Argumentsspecify namesof users or teletypesof interest. If multi pie arguments are given, the informa- 
tion thatappliesto any of theargumentsisprinted. Forexampleiast root consoie would listali of root'ssessionsaswell as 
ali sessionson the console terminal. Last displaysthesessionsof thespecified usersand tei etypes, most recent first, indicati ng 
thetimesat which thesession began, theduration of thesession, and the teletype that the sessi on took place on. If the 
session is stili conti nuing or was cut short by a reboot, ìast so indicates. 

The pseudo-user reboot logs in at rebootsof the system. 

Last with no arguments di splays a record of ali logins and logouts, in reverse order. 

If ìast isinterrupted, it indicates how farthesearch has progressed inwtmp. If interrupted with aquit signal, ìast indicates 
how far the search has progressed so far, and the search conti nues. 

OPTIONS 

-number Limit the number of entries displayed to that specified by n u mb e r . 

-t fi i e ri a me U se f i i e n a me as the name of the accounting fi le instead of /var/iog/wtmp. 

-h hostname List Only loginsfrom host name. 

-i IP address List Only loginsfrom IP address. 



286 
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-i List IP addressesof remote hostsinstead of truncated hostnames. 

-t tty List only loginsontty. 

-y Also report year of dates. 

FILES 

/var/iog/wtmp Logi n database 



20 M arch 1992 



lbxproxy 

ìbxproxy— LBX proxy server for the X Window system 
SYNOPSIS 

lbxproxy [ :di spi aynumber ] [option ...] 

NOTE 

Thismanual pageisnot definitive or "officiai." It isderived from information contai ned in theREADME file in theibx source. 
D ESC RIFIO N 

lbxproxy is the Low Bandwidth X pseudo-server. Itrunson the remote sideoflow bandwidth, high-latency connections, 
such as serial linesand widearea networks. It accepts connections from X clientsat the remote end and forwardsthem to an 
X server at the locai end. The LBX protocol used for the low bandwidth connection includescompression and optimizations 
designed to make effective use of the bandwidth available. Thecurrent version of LBX isnot a standard of theX Consor- 
ti um, and will not becompatiblewith the final version. Thecurrent version should betreated asan "alpha" or "prototype" 
for people interested in experimentingwith it. 

OPTIONS 

lbxproxy acceptsthefollowing options: 

:di spi aynumber lbxproxy runs as thegiven dispiaynumber, which by default iso. A value different from 0 should be 

used if the host running lbxproxy hasalocal X display. If multi pie lbxproxy servers or other X 
servers areto run simultaneously on a host, each must havea unique di splay number. (Seethe 
"D isplay N ames" section of thex(l) manual pageto learn how to specify which display number 
clients should try to use.) 

-ac D isables host-based access control mechanisms. E nables access by any host, and permitsany host to 

modify the access control list. Usewith extremecaution. Thisoption existsprimarily for running 
testsuitesremotely. 

-display di spi ay-number Sets the name of theX server display that lbxproxy connectsto. 
-heip Printsausagemessage. 

-i Causesall remainingcommand-lineargumentsto beignored. 

-to seconds Sets default connection time-out in seconds. 



NETWORK CONNECTIONS 

lbxproxy supportsclient connections via most of the connection types supported bytheX servers. (Referto the xserver(l) 
manual page and hardware-specific X server manual pagesfor details.) N otethat in thecurrent implementation some of the 
connectionstypes nave not been implemented correctly. Thismostly appliesto System V. 




EXAMPLES 

To setup ìbxproxy, start the X server as usuai, and then start the proxy. Theibxproxy is a pseudo-server, so any clientsthat 
wish to useit need to adjust their display. By default, the proxy wi II li sten on <hostname>:i.Thiscan bechanged with the 

:displaynumber argument. 

If the proxy isto berunning on a host named sharedhost, connecting to an LBX-capableX server on a desktop machine 
named mydesktop, you could usethefollowingcommand to start the proxy (which would beknown as display sharedhost: 7): 

mydesktop% rlogin sharedhost 

sharedhost% Ìbxproxy -display mydesktop:0 :7 & 

sharedhost% xclient -display sharedhost:7 

If you arerunning LBX over aTERM connection between mydesktop and sharedhost, try something likethis: 

mydesktop% trsh 

sharedhost* tredir -r 6008 6000 

sharedhost* Ìbxproxy -display sharedhost:8 :7 & 

sharedhost* xclient -display sharedhost:7 

SEEALSO 

General information: x(l) 

Server- SpecifiC man pages: Xserver(l), Xdec(l), Xmacll(l), Xsun(l), Xnest(l), Xvf b(l), XF86_Accel(l), XF86_Mono(l), 
XF86_SVGA(1), XF86_VGA16(1), XFree86(l) 

AUTHORS 

The LBX team includesDaveLemke, DaleTonogai, Keith Packard, Jim Fulton from N CD, and Chris Kanterjievfrom 
Xerox. 

X Versi on 11 Release 6 

ld 

id-TheGNU linker 
SYNOPSIS 

ld [ -o. I output ] . I objf ile . . . . br . rb [ " —A output ] o b j file ... 
[ —A archi tecture ] [-b\ i npjt-format ] [-Bstatic ] [-c\ c omnia ndf il e ] 
[ -d | -de | -dp ] 

[ -defsym\ symbol = expr essi on ][-e\ entry ][-F ][-F\ format ][- 
format\ input-format ][-g ][-G size ][--help ][-i ][-l ar ][- 
L s e a r c hd ì r ] [-M] [-Map ma pf i I e ][-m emulation ] [ -n J -N ] [ - 
noinhibit -exec ][-oformat\ output-format ][-R\ filename ] [-relax ] 
[ -r]-Ur][-S ][-s ] [-sort-common] [-T\ commandfile ][-Ttext\ 
textorg ][-Tdata\ dataorg ][-Tbss\ bssorg ][-t ][-u\ sym ][-V ][- 
v][- -verbose ][--version ] [-warn-common] [-warn-once] [-X ] 
[ -x ] 

D ESC RIFIO N 

id combinesa number of object and archi ve fi les, relocates their data, and tiesup symbol references. Often thelast step in 
building a new compiled program to run isacall to id. 

id accepts Linker Command Language fi lesto provide explicit and total control over the linking process. This man pagedoes 
notdescribethecommand language seetheid entry in info, or themanual Ld: TheGN U Linker, for full detailson the 
command language and on other aspeetsof theG N U linker. 
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This version of id usesthegeneral-purposeBFD librari esto operate on object files. This allows id to read, combine, and 
write object fi les i n many differentformats, forexample, COFF ora.out. Differentformatsmaybelinkedtogetherto 
produce any availablekind of object file. You can useobjdump -i to get a list of formats supported on variousarchitectures; 

Seeobjdump(l). 

Asidefrom itsflexibility, theGN U linker is more helpful than other linkersin provi di ng di agnosti c information. M any 
linkersabandon execution immediately upon encounteringan errar; whenever possi ble, id conti nuesexecuting, allowing 
you to identify other errors(or, in somecases, to get an output fi le in spiteof theerror). 

TheGN U linker id ismeant to cover a broad rangeof situati ons, and to beas compati ble aspossi ble with other li nkers. Asa 
result, you havemany choicesto control itsbehaviorthrough thecommand line, and through environment variables. 

OPTIONS 

The plethora of com mand-l ine opti ons may seem intimidating, but in actual practicefew of them areused in any parti cular 
context. For instance, afrequent useof id i sto link standard U N IX object fi les on a standard, supported UNIX system. On 
such asystem, thi s li ne li nks a fi le hello . o : 
$ ld -o output /lib/crt0.o hello. o -le 

Thistellsid to produce a file called output asthe result of linking the fi le /nb/crta.o with hello, o and the library ìibc.a, 
which will comefrom thestandard search directories. 

Thecommand-lineoptionsto id may bespecified in any order, and may berepeated at will. For themost part, repeating an 
option with a different argument will either have no further effect or override prior occurrences (thosefurther to the left on 
thecommand line) of an option. 

T he exceptions— which may meaningfully beused more than once— are -a, -b (or itssynonym -format), -defsym, -l, -1, -r, 
and -u. 

T he list of object fi les to belinked together, shown asobjfiie, may follow, precede or bemixed in with command-line 
options, except that an objme argument may not beplaced between an option flag and its argument. 

Usually the linker isinvoked with at leastone object fi le, but other formsof binary input files can also bespecified with -1, 
-R, and the script command language. If no binary input fi les at ali arespecified, the linker doesnot produce any output, and 
issuesthemessageNo input fiies. 

0 ption arguments must either follow the option letter without i ntervening whitespace or be gi ven as separate arguments 
immediately following the option that requiresthem. 

-Aarchi tecture In thecurrent releaseof ìd, thisoption isuseful only for the Intel 960 family ofarchitec- 

tures. In that id configuration, thearchitecture argument isoneof the two-letter names 
identifying membersof the 960 family; theoption specifi es the desi red output target and 
warnsof any i ncompatible instructions in the input fi les. It also modifies the linker's search 
strategy for archi ve librari esto support the useof librari es specifi cto each parti cular 
architecture, by including in the search loop names suffixed with thestring identifying the 
architecture. 

Forexample, if yourid command lineincluded -aca aswell as-itry, the linker would look 
(in itsbuilt-in search paths, and in any pathsyou specify with -l) for a library with the 
names 

try 

libtry.a 
tryca 

libtryca.a 

Thefirsttwo possi bi I ities would beconsidered in any event; thelasttwo are due to theuse 
of -aca. 

F utu re rei eases of id may support similar functionality for other archi tecture f am i I i es. 



Id 




You can meaningfully use -a morethan onceon acommand line, if an arch itectu re fam i ly 
allowscombination of target arch itectu res; each usewill add another pair of namevariants 
to search forwhen -ì specifies a library, 
-b i nput-format Specify the binary format for i nput object files that follow this option on thecommand line. 

You don't usually need to specify this, asid isconfigured to expect as a default input format 
themost usuai format on each machine, nput- format isatext string, thenameof a partic- 
ular format supported bytheBFD libraries. 

-format i nput-format 

hasthesameeffect, asdoes the script command target. 

You may wantto use this option if you are linking fi leswith an unusual binary format. You 
can also use-b to switch formatsexplicitly (when linking object filesof different formats), 
by includi ng 

-b nput ■ f or ma t 

beforeeach group of object files in a parti cular format. 

The default format istaken from theenvironment variable gnutarget. You can also define 
the input format from a seri pt, using the command target. 
-Bstatic Thisflag isaccepted for command-line compati bility with the SunOS linker, but has no 

effect on m. 

-c commandf i i e D ireetsid to read link commandsfrom thefilecommandfiie. Thesecommandswill 

completely override ìd's default link format (ratherthan adding to it); commandf ile must 
specify everything necessary to describe the target format. 

You may also include a script of link commandsdirectly in thecommand lineby bracketing 
it between { and } characters. 

-d, -de, -dp Thesethreeoptionsareequivalent; multiple formsaresupported for compati bility with 

other linkers. Useany of them to make id assign space to common symbolseven if a 
relocatable output file isspecified (-r). T he script command force_common_allocation has 
th esame effect. 

-defsym symbol = expressi on C reate a global symbol in the output fi le, contai ni ng the absolute address given by 

ex pressi on. You may usethisoption asmany timesas necessary to define multi pie symbols 
in thecommand line. A limited form of arithmetic is supported for theexpr essi on in this 
context; you may giveahexadecimal Constant or the nameofan existing symbol, oruse + 
and - to add or subtract hexadecimal constants or symbols. If you need more elaborate 
expressions, consider using the linker command languagefrom a script. 

-e entry Useentry as the explicit symbol for begi nning execution of your program, rather than the 

default entry point. 

-f, -Ff or mat Someolder linkers used this option throughout a compilation toolchain for specifying 

object- fi le format for both input and output object files. id'smechanisms(the-b or -format 
options for input files, theTARGET command in linker seri ptsfor output files, theGNUTARGET 
environment variable) are more flexible, but it accepts(and ignores) the-F option flagfor 
compati bility with seri pts written to cali theold linker. 

-format input-format Synonymfor-b i n p ut - f o r mat . 

-g Accepted, butignored; provided for compati bility with other tools. 

-g si ze Set the maximum sizeof objects to beoptimized using the G P regi ster to s ze under M IPS 

ECOFF. Ignored for other object fi le formats. 
--heip P ri nt a summary of the command-line options on the standard output and exit. This option 

and --version begi n with two hyphensinstead ofone for compati bility with other GN U 

programs. The other options start with only onehyphen for compati bility with other 

linkers. 

-i Perform an incrementai link (sameasoption -r). 
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-la r 

-Lsearchdi r 



-M 

-Map ma p f i I e 
-m e mu I a t i o n 

-N 
-n 

-noinhibit-exec 

-o o ut puf o ut put 
-oformat output-format 

-R fi I e ri a me file 
-relax 



-S 



-sort-common 



Add an archivefile ar to the list off i lesto link. Thisoption may beused any number of 

times. id will search itspath list for occurrences of iìb ar .aforevery ar specified. 

Thiscommand addspath searcndir to the list of pathsthatid will search for archive 

libraries. You may use thisoption any number of times. 

Thedefault set of pathssearched (without being specified with -l) dependson what 

emulation modeid isusing, and in somecasesalso on how itwas confi gured. Thepaths 

can also be specified in a link script with thesEARCH_DiR command. 

Print (to the standard output file) a link map— diagnostic in-formation aboutwhere 

symbolsaremapped by id, and informati on on global common Storage allocation. 

Print to the fi le ma pf i i e alink map— diagnostic information aboutwheresymbolsare 

mapped by id, and information on global common Storage allocation. 

Emulate the e mui ati on linker. You can list the available emulations with the --verbose 

option. Thisoption overrides the compiled-in default, which isthesystem forwhich you 

confi gured id. 

Specifiesreadableand writabletext and data sections. If the output format supports 

UN IX-style magic numbers, the output ismarked asoniAGic. 

When you use the -n option, the linker does not page-align the data segment. 

Setsthetextsegmentto beread-only, and magic iswritten if possi ble. 

N ormally, the linker will not produce an output file if it encounters errors during the link 

process. With thisflag, you can specify that you wish theoutput file retai ned even after 

nonfatal errors. 

output isa namefor the program produced by id; if thisoption is not specified, thename 
a.out isused by default. The script command output can also specify the output filmarne. 
Specify the binary format for the output object file. You don't usually need to specify this, 
asid isconfigured to produce as a default output format the most usuai format on each 
machine, output-format isatext string, the nameof a particular format supported bythe 
BFD libraries. The script command output_format can also specify the output format, but 
thisoption overrides it. 

Read symbol namesand their addressesfrom f ename, but do not relocate it or include it in 
theoutput. Thisallowsyour output fileto refer sym boli cai ly to absolute locations of 
memory defined in other programs. 

An option with machine-dependent effects. Currently thisoption isonly supported on the 
H 8/300. 

On someplatforms, use this option to perform global opti mizations that become possi ble 
when the linker resolves addressing in your program, such as relaxing address modes and 
synthesizing new instructions in theoutput object file. 
On platformswhere this is not supported, -relax isaccepted, but hasno effect. 
Generatesrelocatable output, that is, an output fi le that can in turn serve as input to id. 
This is often called parti al linking. As a side effect, in environments that support standard 
UNIX magic numbers, thisoption also sets the output fi le's magic number tooniAGic. If this 
option is not specified, an absolute file is produced. When linking C++ programs, this 
option will not reso I ve referen cesto constructors; -ur isan alternative. 
Thisoption does thesameas-i. 

Omitsdebugger symbol information (but notali symbols) from the output fi le. 
Omitsall symbol information from the output fi le. 

N ormally, when id places the global common symbols in the appropriate output sections, it 
sortsthem bysize. First corneali the one-byte symbols, then ali thetwo bytes, then ali the 
four bytes, and then everything else. This isto prevent gapsbetween symbols due to 
alignment constraints. Thisoption disablesthat sorting. 




-Tbss org, -Tdata org, 
-Ttext org 

-T c o mma n d F i I e , -Te o mma n d f il e 
-t 

-u sym 
-Ur 

- -verbose 

-v, -V 
- -version 
-warn-common 



-warn-once 
-X 
-x 

ENVIRONMENT 

You can changethebehaviorof id with theenvironment variableGNUTARGET. 

gnutarget determi nes the i nput-fi le object format if you don'tuse-b (or itssynonym -format). Itsvalue should beoneof the 
BFD namesforan input format. If thereisno gnutarget in theenvironment, id uses the naturai format of the host. If 
gnutar-get i s set to defauit , then BFD attempts to discover the input format by examining binary input files; this method 
often succeeds, butth ere are potenti al ambiguities, sincethereisno method of ensuring that the magic number used to flag 
object-fileformats isunique. However, theconfiguration procedure for BFD on each system placestheconventional format 
for that system first in the search- list, so ambiguities are resolved in favor of convention. 

SEEALSO 

objdump(l); ìd and binuuis entries in info 

Ld:TheGNU Linker, Steve C hamberlain and Roland Pesch;TheGNU Binary U tilities, Roland H . Pesch. 
COPYING 

Copyright © 1991, 1992 F ree Software Foundation, Inc. 

Permission isgranted to makeand distribute verbatim copiesof thismanual provided thecopyright noticeand this 
permission noticearepreserved on ali copies. 

Permission isgranted to copy and distribute modifi ed versi onsof thismanual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof thismanual into another language, under the above conditions 
for modifi ed versi ons, except that this permission notice may beincluded in translationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

Cygn us supporr., 17 August 1992 



Use org as the starting addressfor— respectively— thebss, data, or thetext segment of the 

output file, textorg must be a hexadecimal integer. 

Equivalentto -c c o mma n df i i e; supported for compatibilità with othertools. 

P ri nts names of i n put f i I es as id processes them. 

Forces sym to beentered in the output file asan undefined symbol. This may, for example, 

trigger linking of additional modulesfrom standard libraries. -u may berepeated with 

different option argumentsto enter additional undefined symbols. 

For anythi ng other than C++ program s, this option is equivalentto -r : it generates 

relocatable output, that is, an output fi le that can in turn serve as in put to id. W hen linking 

C++programs, -ur will resolvereferencesto constructors, unii ke -r. 

D isplay theversion number for id and list the supported emulations. Display which input 

fi les can and can not be opened. 

D isplay theversion number for id. 

D isplay theversion number for id and exit. 

Warn when a common symbol iscombined with another common symbol or with a symbol 
definition. UNIX linkersallow thissomewhat sloppy practice, but linkerson some other 
operati ng systemsdo not. This option allowsyou to find potenti al problemsfrom 
combiningglobal symbols. 

Only warn once for each undefined symbol, ratherthan once per modulethat refersto it. 
If -s or-s isalso specified, delete only locai symbols beginningwith l. 
If -s or -s isalso specified, del ete al I locai symbols, not just those beginningwith l. 
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lispmtopgm 

ìispmtopgm— Convert a Lisp M achinebitmap file into PGM format 
SYNOPSIS 

lispmtopgm [lisp mf ile] 

D ESC RIFIO N 

lispmtopgm reads a Lisp machinebitmap as input and produce a portable graymap as output. 

T his is the f i le format written by thetv:write-bit-array-fiie function on TI Explorer and Symbolics Lisp machines. 

M ultiplanebitmapson Lisp machines are color; buttheiispm image fi le format doesnot include a colormap, so it must be 
treated as a graymap instead. Thisisunfortunate. 

SEEALSO 

pgmtolispm(l), pgm(5) 

BUGS 

Theiispm bitmap fi le format isa bit quirky; Usually the image in the file has itswidth rounded up to thenext higher 
multiple of 32, but not always. If the width isnot a multiple of 32, wedon't deal with it properly, but becauseof theiispm 
microcode, such arrays are probably not image data anyway. 

Also, theiispm code for savi ng bitmapshasa bug, in that if you are writing a bitmap that isnot mod32 across, thefilemay be 
up to seven bitstoo short. They round down instead of up, and wedon't handle this bug gracefully. 

No color. 
AUTHOR 

Copyright© 1991 byJamieZawinski andjef Poskanzer. 

6 M arch 1990 

lkbib 

ìkbib— Search bibliographic databases 
SYNOPSIS 

lkbib [ -v ] [ — if i e I d s ][-pf Menarne ][-tn ] k e y ... 

DESCRIPTION 

lkbib searches bibliographic databases for referencesthat contai n the keyskey. . . and printsany references round on the 
standard output, lkbib will search any databases given by -p options, and then a default database. The default database is 
taken from the refer environment variableif it is set, otherwise it is 

/usr/dict/papers/Ind. 

For each database menarne to besearched, if an index menarne.! created by gindxbib(l) exists, then itwill besearched 
instead; each index can cover multipledatabases. 

OPTIONS 

-v P ri nt the versi on number. 

-pf m ename Search f i i ename. M ulti pie -p optionscan beused. 

-istri ng When searching files for which no index exists, ignore the contents of fields whose names are in st r ng. 

-tn Only requirethefirstn characters of keysto be given. Ini ti al I y n is 6. 



ENVIRONMENT 

refer D efault database 



FILES 

/usr/dict/papers/md Default database to beused if the REFER environmentvariableisnotset. 

filename.i Indexfiles. 

SEEALSO 

grefer(l), glookbib(l), gindxbib(l) 

Groff Version 1.09, 6 August 1992 



In 

in— M ake links between files 
SYNOPSIS 

In [options] source [dest] 

In [options] source... directory 

Options: 

[-bdfinsvF] [-S backup-suff ix] [-V {numbered,existing,simple}] 
[ - - version - cont rol={numbe red, existing , simple} ] [ - -backup] [ - -directory] 
[--force] [ - -interactive] [--no-dereference] [--symbolic] [--verbose] 
[ - -suff ix=backup-suff ix] [--help] [--version] 



D ESC RIFIO N 

Thismanual page documents the GN U version of in. If thelast argument namesan existing directory, in links each other 
given fileinto a fi le with the sanie name in that directory. If only onefileisgiven, it linksthat fileinto thecurrent directory. 
Otherwise, if only two files are given, it links the first onto thesecond. It isan errar if thelast argument isnot a directory 
and morethan two files are given. Itmakeshard links by default. By default, itdoesnot remove existing files. 



OPTIONS 



-b, --backup 

-d, -F, --directory 

-f, --force 

-i, --interactive 

-n, --no-dereference 



-s, --symbolic 

-v, --verbose 
- -help 
- -version 

-S, --suffix backup-suff ix 



M ake backupsof files that are aboutto beremoved. 
Allow thesuperuserto makehard links to directories. 
Remove existing desti nati on files. 
Promptwhetherto remove existing desti nation file. 

When the specified desti nation is a symbolic linkto a directory, attemptto replace the 

symbolic link rather than dereferencing it to create a link in the directory to which it points. 

Thisoption ismost useful in conjunction with -force. 

M ake symbolic links instead of hard links. Thisoption produces an errar messageon 

systemsthat do not support symbolic links. 

P ri nt the name of each fi le before li nki ng i t. 

P ri nt a usage messageon standard output and exitsuccessfully. 

Print version information on standard output then exitsuccessfully. 

The suffix used for maki ng si mple backup fi les can be set with the simple_backup_suffix 

environment variable, which can beoverridden by thisoption. If neither of thoseis given, 

the default is asitisin Emacs. 
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-v, --version-controi Thetypeof backups made can besetwith the version_control environment variable, which 

{numbered,existing,simpie} can beoverridden by thisoption. If version_control is not set and this option is not given, 
the default backup type i s existing. T he value of the version_control environment variable 
and theargumentto thisoption are liketheGN U E macs version-controi variable they 
also recognizesynonymsthat aremoredescriptive. The vai id values(unique abbrevi ations 
areaccepted) are thefollowing: 

t or numbered Always make numbered backups. 

nii or existing Makenumbered backupsof filesthatalready havethem, simple 

backups of the others. 
never or simpie Always make sim pie backups. 

GNU F i le U ti I i ti es 

Indir 

indir— C reate a shadow directory of symbolic linksto another directory tree 
SYNOPSIS 

indir fromdir [todir] 

D ESC RIFIO N 

indir makes a shadow copy todir of a directory tree fromdir, exceptthat the shadow isnot populated with real files but 
instead with symbolic links pointingat the real files in thefromdir directory tree. This is usuai ly useful for maintaining 
sourcecodefor different machine architectures. You create a shadow directory contai ni ng linksto the real source which you 
will haveusually N FS mounted from a machineof a different architecture, and then recompi le it. The object files wi II bein 
the shadow directory, whi le the source files in the shadow directory are just symlinksto the real files. 

Thishastheadvantagethat if you update the source, you need not propagate the changeto the other architectures by hand 
because al I sou ree i n sh adow d i recto ries are symlinksto the real thing: J ust ed to theshadow di rectory an d reco m pi I e away . 

The todir argument is optional and defaults to thecurrent directory. Thefromdir argument may be relative (for example, 
. ./src) and isrelativeto todir (not thecurrent directory). 

N otethat rcs, sccs, and cvs.adm di recto ries are not shadowed. 

If you add files, simply run indir again. D eleting files isa more painful problem; the symlinks will just point into never- 
neverland. 

BUGS 

patch getsupset if it cannot change the files. You should never run patch from a shadow directory anyway. 
You need to usesomething likethis: 

find todir -type 1 -print j xargs rm 

to clear out ali files beforeyou can relink (if fromdir moved, for instance). Something likethis: 

find . \ ! -type d -print 

will find ali filesthat are not directories. 

X Versi on 11 Re!ease6 



logger 




locate 

locate— List files in databasesthat match a pattern 
SYNOPSIS 

locate [-d path] [ - -database=path] [--version] [--help] pattern... 

D ESC RIPTIO N 

Thismanual page documents the GN U version of locate. For each given pattern, locate searchesoneor moredatabasesof 
filenamesand displaysthefilenamesthat contain the pattern. Patternscan contain shell-style meta characters: *, ?, and []. 
Themetacharactersdo nottreat / or . speci al ly. Therefore, a pattern foo*bar can match afilenamethat contai nsfoo3/bar, 
and apattern *duck* can match afilenamethat containsiake/.ducky. Patternsthat contain meta characters should bequoted 
to protectthem from expansion bytheshell. 

If a pattern isa plain string— it contai ns no meta characters— locate displaysall filenames in the database that contain that 
stringanywhere. If apattern does contain meta characters locate onlydisplays filenames that match the pattern exactly. Asa 
resul t, patternsthat contain meta characters should usuai ly begin with a * and will mostoften end with oneaswell. The 
exceptions are patternsthat are intended to explicitly match thebeginningorend of afilename. 

The fi lenamedatabases contain li stsof files that wereon thesystem when thedatabaseswerelastupdated. Thesystem 
administrator can choose the fi lenameof the default database, the frequency with which thedatabasesareupdated, and the 
directories for which they contain entri es; seeupdatedb(lL). 

OPTIONS 

-d path , --database=path Instead of searching the default fi lename database, search the fi lenamedatabases in path, 
which isacolon-separated list of database filenames. You can also usetheenvironment 
variable locate_path to set the list of database fi lesto search. The option overridesthe 
environment variableif both areused. 

Thefilenamedatabaseformat changed starti ng with GN U find and locate version 4.0 to 
allow machineswith different byte orderingsto sharethedatabases. Thisversion of locate 
can automatically recognizeand read databasesproduced for older versi onsofGN U locate 
or UN IX versionsof locate or find. 

--heip Printasummary of theoptionsto locate and exit. 

--version Print the version numberof locate and exit. 

ENVIRONMENT 

locate_path C olon-separated listof databasesto search 

SEE ALSO 

find(lL), iocatedb(5L), updatedb(lL), xargs(lL), Finding Files(onlinein info, or printed) 

logger 

ìogger— M ake entries i n the system log 
SYNOPSIS 

logger [-is] [-f file] [-p pri] [-t tag] [message ...] 



DESCRIPTION 

ìogger provi des a shell command interface to the sysiog(3) system log modula 
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OPTIONS 

-i LogtheprocessID of the logger processwith each line, 
-s Logthemessageto standard errar, aswell asthesystem log. 
-f file Log the specified file. 

-p pr Enterthemessagewith thespecified priority. Thepriority may be specified numerically or asafacmty.ievei 
pair. For example, -p iocai3.info logsthemessage(s) asinformational level in the local3 faci I ity. The default is 

user.notice. 

-t tag M ark every line in the log with thespecified tag. 

message W rite the message to log; if not specified, and the -f flag is not provided, standard input is logged. 
The logger utility exits 0 on success, and >o if an errar occurs. 

EXAMPLE 

logger system rebooted: 

logger -p locala. notice -t HOSTIDM -f /dev/ìdmc 

SEEALSO 

syslog(3), syslogd(8) 

STANDARD S 

Theiogger command isexpected to be compati ble with IEEE Std 1003.2 (POSIX). 

BSD 4.3, 6Junel993 



login 

ìogin— Sign on 
SYNOPSIS 

login [ n a me ] 

login -p 

login -h host name 

login -f nane 

DESCRIPTION 

login isused when signing on to asystem. It can also beused to switch from oneuser to another atany time. (M ost modem 
shells have support for this feature built i nto them, however.) 

If an argument is not given, ìogin prompts for the username. 

If the user isnot root, and if /etc/noiogin exists, thecontentsof thisfileareprinted to thescreen, and the login is termi- 
nateci. This is typically used to prevent loginswhen the system isbeingtaken down. 

If the user isroot, then the login must beoccurring on atty listed in /etc/securetty. Failureswill be logged with thesysiog 
faci I ity. 

After these condì tions are checked, the password will berequested and checked (if a password is required for this username). 
Ten attemptsareallowed beforeiogin dies, but after the first three, theresponsestartsto get very slow. Login fai lures are 
reported via thesysiog facility. Thisfacility isalso used to report any successful rootlogins. 

If the fi le .hushiogin exists, then aquiet login isperformed (this disables the checking of thechecking of mail and the 
printing of thelast login ti me and message of the day). Otherwise, if /var/iog/iastiog exists, thelast login time isprinted 
(and the current login isrecorded). 




Random administrativethings, such assetti ng theU ID and GID of thetty, areperformed. TheTERM environment variableis 
preserved, if it exists; other environment variables are preserved if the -p option isused. Then the home, path, shell, term, 
mail, and logname environment variables are set. path defaultsto /usr/iocai/bin:/bin:/usr/bin:. for normal users, and to / 
sbin:/bin:/usr/sbin:/usr/bin for root. Last, if this is not a quiet login, the message of the day isprinted and thefilewith the 
user'snamein /usr/spooi/maii will bechecked, and a message printed if it has nonzero length. 

T he user's shell isthen started. If no shell isspecified for the user in /etc/passwd, then /bin/sh isused. If thereisno directory 
specified in /etc/passwd, then / isused. (The home directory ischecked for the .hushiogin filedescribed earlier.) 

OPTIONS 

-p Used by getty(8) to teli login not to destroy the environment. 

-t Used to skip a second login authentication. This specifically doesnot work for root, and doesnot appear to work 
well under Linux. 

-h Used by other servers(such asteinetd(8)) to pass the nameof the remote hostto login so that it may beplaced in 
utmp andwtmp. Only thesuperuser may use this opti on. 

FILES 

/var/run/utmp 

/var/log/wtmp 

/var/log/lastlog 

/usr/spool/mail/* 

/etc/motd 

/etc/passwd 

/etc/nologin 

/etc/usertty 

. hushiogin 

SEEALSO 

init(8), getty(8), mail(l), passwd(l), passwd(5), environ(7), shutdown(8) 

BUGS 

Linux, unlike other D raconian operating systems, does not check quotas. 

Theundocumented BSD -r option isnot supported. This may berequired by somenogind(8) programs. 
AUTHOR 

Derivedfrom BSD login 5.40 (M ay 9, 1989) by M ichael Glad (giadedaimi.dk) for H P-UX Ported to Linux 0.12: Peter 

Orbaek (poeMaimi.aau.dk). 

Linux 0.99, 1 February 1993 

look 

look— D isplay lines beginning with a given string 
SYNOPSIS 

look [-dfa] [-t termchar] string [file] 

D ESC RIFIO N 

The look utility displaysany lines in file that contai n string asa prefix. Asiook performsabinary search, the lines in file 
must besorted. 
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If fileisnot specified, the file /usr/dict/words isused, only alphanumeric charactersarecompared, and the case ofalphabetic 
charactersisignored. 

OPTIONS 

-d D ictionary character set and order; that is, only alphanumeric charactersarecompared. 
-f Ignore the case of alphabetic characters. 
-a Use the alternate dictionary /usr/dict/web2. 

-t Specify a stri ng termi nation character; that is, only the characters in string up to and includi ng the first 
occurrenceof termchar arecompared. 

The look utility exitse if oneor morelineswerefound and displayed, 1 if no lineswerefound, and >i if an errar occurred. 
FILES 

/usr/dict/words T he dictionary 
/usr/dict/web2 T he alternate dictionary 

SEEALSO 

grep(l), sort(l) 

COMPATIBILITY 

The originai manual pagestated that tabs and blank characters parti ci pated in comparisonswhen the -d option was specified. 
Thiswasincorrect and thecurrent man page matches the historic implementation. 

HI STORY 

look appeared in version 7 AT&T U N IX. 

14 Junel993 

lpq 

ìpq— Spool queueexamination program 
SYNOPSIS 

lpq [-1] [-P printer] [job # ...] [user ...] 

D ESC RIFIO N 

ìpq examines the spooling area used by ipd(8) for printingfileson the li ne printer, and reports the status of the specified jobs 
or ali jobs associ ated with auser. ìpq invoked without any arguments reports on any jobs currently in the queue. 

OPTIONS 

-p Specify a parti cular printer; otherwise the default line printer isused (or the valueof the printer variablein the 
environment). Ali other arguments supplied areinterpreted as usernames or job numbersto filter out only those 
jobs of interest. 

-ì Information about each of the fi les compri si ng the job entry is printed. N ormally, only as much information as 
will fiton onelineisdisplayed. 

For each job submitted— in other words, each timeipr(l) is invoked— ìpq reports the user's name, current rank in the 
queue, thenamesof fi les compri si ng the job, the job identifier (a number that may be supplied to iprm(l) for removinga 
specific job), and the total sizein bytes. Job ordering isdependent on thealgorithm used to scan the spooling directory and is 
supposed to be FI FO (First in First Out). Filenamescomprisingajob may beunavailable(when ipr(l) isused asasink in a 
pipeline) in which case the file is indicated as (standard input). 




If ìpq warnsthat there isno daemon present (dueto somemalfunction, for example), theipc(8) command can beused to 
restart the pri nter daem o n . 

ENVIRONMENT 

If thefollowing environment variable exists, it isused by ìpq: 
printer Specifiesan alternate default printer 

FILES 

/etc/printcap 
/var/spool/* 
/var/spool/*/cf * 
Pa/var/ spool /*/lock 
/usr/share/misc/termcap 

SEEALSO 

lpr(l), lprm(l), lpc(8), lpd(8) 

HI STORY 

ìpq appeared in BSD 3. 

BUGS 

Dueto thedynamic nature of theinformation in the spool ing directory, ìpq may report unreliably. Output formatti ng is 
sensitive to the line length of the terminal; thiscan result in widely spaced columns. 

DIAGNOSTICS 

U nableto open variousfiles. The lock file is malformed. Garbagefileswhen there isno daemon active, but filesin the 
spooling directory. 

BSD 4.2,9 Mayl991 

lpr 

ìpi — O ffli ne print 
SYNOPSIS 

lpr [-P printer] [-# num] [-C class] [ -J job] [-T title] [-U user] 
[-i [numcols]] [-1234 font] [-w num] [ -cdfghlnmprstv] [name ...] 

DESCRIPTION 

ipr uses a spooling daemon to print the named fileswhen facilities become available. If no namesappear, the standard input 
isassumed. 

Thefollowing single-letter optionsareused to notify the line printer spooler that the files are not standard text files. The 
spooling daemon will usetheappropriatefiltersto print the data accordi ngly. 

-c Thefilesareassumed to contain data produced by cifpiot(l). 

-d Thefilesareassumed to contain datafrom TeX (DVI format from Stanford). 

-f U se a filter that interprets thefi rst character of each li ne as a standard FORTRAN carri age control character. 
-g Thefilesareassumed to contain standard plot data as produced by the plot routines. (Seealso plot forthefilters 
used by the printer spooler.) 



To determine printer characteristics 

The spool ing directory, asdetermined from printcap 

Control files specifyingjobs 

The lock fileto obtain thecurrently active job 

For manipulating thescreen for repeated display 
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-# num 



-ì U se afilter that allowscontrol charactersto beprinted and suppresses page breaks. 

-n Thefilesareassumed to contai n datafrom diti-off (deviceindependent troff). 

-p Usepr(l) to format the fi les (equi valent to print). 

-t Thefilesareassumed to contain datafrom troff(l) (cat phototypesetter commands). 

-v Thefilesareassumed to contain a raster imagefordevices like the Benson Varian. 

T hese options apply to the handli ng of the pri nt j ob: 

-p Force output to aspecific printer. N ormally, the default printer isused (site-dependent), or thevalueof the 

environment variatile printer isused. 
-h Suppress the pri nti ng of the burst page, 
-m Send mail upon completion. 

-r Remove the file upon completion of spool ing or upon completion of printing (with the -s option). 

-s Use symbol ic links. Usually, filesarecopied to the spool directory. The -s option will usesymiink(2) to link data 

fi les rather than tryingto copy them so largefilescan beprinted. Thismeans the fi les should not bemodified or 

removed until they havebeen printed. 

The remaining options apply to copies, the page display, and headers: 

Thequantity num is the num ber of copies desi red of each filenamed. For example, 

lpr -#3 foo.c bar.c more.c 

would result in three copies of the fi le foo.c, followed by three copies of the file bar.c, and so on. On the 
other hand, 

cat foo.c bar.c more.c ] lpr -#3 

will give three copi esof the concatenati on of thefiles. Often a si te w i 1 1 disablethisfeatureto encourageuse 
of a photocopier instead. 

Specifies a font to bemounted on font position i . Thedaemon will construct a .raiimag fi le referenti ng 
thefont pathname. 

J ob classification to use on the burst page. For example 

lpr -C EECS foo.c 

causes the system name-thenamereturned by hostname(l)— to bereplaced on the burst page by EECS, 
and thefilefoo.c to beprinted. 

Job nameto printon the burst page. N ormally, the first fi le'sname isused. 
Titlenameforpr(l), instead of thefilename. 

Usernameto printon the burst page, also for accounting purposes. This option isonly honored if thereal 
user ID isdaemon (or that specified in the pri ntcap file instead of daemon), and isintended forthose 
instanceswhere print filters wish to requeuejobs. 

The output is indented. If thenext argument isnumeric numcois, it isused asthenumber of blanksto be 
printed beforeeach line otherwise, eight characters are printed. 
Usesnum as the page width forpr(l). 



1234 font 



-C Ar class 



■J Ar job 
-T Ar title 
-U user 



-i numcois 



-w Ns Ar num 



ENVIRONMENT 

If thefollowing environment variable exists, it is used by ipr: 
printer Specifies an alternate default printer 

FI LES 

etc/passwd Personal identification. 

/etc/printcap Printer capabi li ti es database, 

/usr/sbin/ipd* Line printer daemons. 

/var/spooi/output/* D i rectories used for spooling. 




/var/spooi/output/*/cf* Daemon control files. 
/var/spooi/output/*/df* D ata files specified in et files. 
/var/spooi/output/*/tf * Temporary copiesof cf files. 

SEEALSO 

lpq(l), lprm(l), pr(l), symlink(2), printcap(5), lpc(8), lpd(8) 

HI STORY 

Theipr command appeared in BSD 3. 

DIAGNOSTICS 

If you try to spool too largeafile, it will betruncated. ipr will object to printing binary files. If a user otherthan root printsa 
fi le and spooling isdisabled, ipr will print a messagesaying so and will not put jobsin thequeue. If a connection toipd(l) 
on the locai machine cannot bemade, ipr will say that the daemon cannot bestarted. D iagnostiesmay beprinted in the 
daemon'slogfileregarding missing spool files by ipd(l). 

BUGS 

Fontsfor troff(l) and TeX resi de on thehost with the printer. It iscurrently not possibleto use locai font libraries. 

BSD 4, 24 July 1991 



lprm 

ìprm— Remove jobsfrom the line printer spooling queue 
SYNOPSIS 

lprm [-P printer] [- job # ...] [user ...] 

D ESC RIFIO N 

lprm will remove a job, or jobs, from aprinter'sspool queue. Since the spooling directory isprotected from users, using ip™ 
isnormally theonly method by which a user may remove a job. The owner of a job is determi ned by theuser's login name 
and hostnameon themachinewheretheipr(l) command wasinvoked. 

Optionsand arguments: 

-p printer Specify the queue associateci with aspecific printer; otherwise, the default printer isused. 

If a single - isgiven, lprm will remove ali jobs that a user owns. If thesuperuser employsthisflag, the spool 
queue will beemptied enti rely. 

user Causesiprm to atterri ptto removeanyjobsqueued belongingto that user (or users). Thisform of invoking 

iprm isuseful onlyto thesuperuser. 
job # A user may dequeuean individuai job by specifying itsjob number. Thisnumber may beobtained from 

theipq(l) program. Forexample 

lpq - -1 

1st:ken [ job#013ucbarpa] 

(standard input) 100 bytes 

lprm 13 

If neither arguments nor options aregi ven, iprm will delete the currently acti ve job if it isowned by the user who invoked 

lprm. 

iprm announcesthenamesof any files it removes and issilent if there areno jobsin the queue that match therequest list. 

iprm will ki II off an acti ve daemon, if necessary, before removi ng any spooling files. If a daemon iskilled, a new oneis 
automatically restarted upon completion of fi le rem ovai s. 
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ENVIRONMENT 

If thefollowing environment vari able exi sts, it is utilizai by iprm: 

printer If the environment variable printer exists, and a printer hasnot been specified with the -p option, the default 
printer isassumed from printer. 

FILES 

/etc/printcap Printer characteri sticsfi le 

/var/spooi/* Spooling directories 

/var/spooi/*/iock Lock file used to obtain the pici of thecurrent daemon and thejob number of thecurrently active 
job 

SEEALSO 

lpr(l), lpq(l), lpd(8) 

DIAGNOSTICS 

"Permission denied" if the user triesto remove filesotherthan hisown. 
BUGS 

B ecause there are race condì tions possi ble in the update of the lock file, thecurrently active job may beincorrectly identified. 
HI STORY 

Theiprm command appeared in BSD 3.0. 

BSD 4.2,9 May 1991 
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ìptest— G enerate I i ne pri nter ri ppl e pattern 
SYNOPSIS 

lptest [length] [count] 

D ESC RIFIO N 

ìptest writes the traditional "ripple test" pattern on standard output. In 96 lines, this pattern will print ali 96 printable 
ASCII characters in each position. Although ori gi nally created to test printers, it is quite useful for testi ng termi nals, drivi ng 
terminal portsfor debugging purposes, or any other task whereaquick supply of random data isneeded. 

The length argument specifies the output line length if the default length of 79 is inappropriate. 

The count argument specifies the number of output linesto begenerated if the default count of 200 is inappropriate. N ote 
that if count isto be specified, length must also be specified. 

HI STORY 

ìptest appeared in BSD 4.3. 

BSD 4.3, 9 M ay 1991 



Is, dir, vdir 




ls,dir,vdir 

is, dir, vdir— List contentsof directories 
SYNOPSIS 

ls [-abcdfgiklmnpqrstuxABCFGLNQRSUXI ] [-w cols] [-T cols] [-1 pattern] [--ali] 
[--escape] [--directory] [--inode] [ - -kilobytes] [ - -numeric-uid-gid] [-no-group] 
[ - -hide-control-chars] [--reverse] [--size] [ - -width=cols] [ - -tabsize=cols] 
[ - -almost-all] [ - -ignore-backups] [--classify] [ - -f ile-type] [--full-time] 
[ - -ignore=pattern] [ - -dereference] [--literal] [ - -quote-name] [ - -recursive] 
[-- -sortanone, time, size, extension}] [ - -format={long, verbose, commas, 
across, vertical, single -column}] [ - -time={atime, access, use, ctime, status}] 
[--help] [--version] [name...] 



D ESC RIFIO N 

Thismanual page documents the GN U version ofis. dir and vdir areversionsof is with different default output formats. 
Theseprogramslisteach given fi le or directory name. D irectory contentsaresorted al ph abeti cai ly. For is, filesareby default 
listed in columns, sorted vertically, if the standard output is a terminal; otherwise, they are listed one per line For dir, files 
areby default listed in columns, sorted vertically. For vdir, filesareby default listed in long format. 



OPTIONS 

-a, - -ali 
-b, - -escape 

-c, - -time=ctime, 

- -time=status 

-d, - -directory 
-f 

- -full-time 

-g 

-i, - - inode 
-k, - -kilobytes 

-1, - -format=long, 

- -f ormat=verbose 



-m, - -f ormat=commas 
-n, - -numeric-uid-gid 
-P 

-q, - -bide-control-cbars 
-r, - -reverse 
-s, - -size 

-t, - -sort=time 

-u, - -time=atime, 

- -time=access, - -time=use 



Listali filesin directories, includi ng ali fi lesthat start with aperiod (.). 

Quote nongraphic characters in filenames using alphabetic and octal backslash sequences 

likethoseused in C. 

Sort directory contents accordi ngto the files' status change ti me instead of the modificati on 
time. If the long I isti ng format is bei ngused, print the status change ti me instead of the 
modification time 

List directories like other files, ratherthan listi ng thei r contents 

D o not sort directory contents; list them in whatever order they are stored on the disk. This 

isthesameasenabling-a and -u and disabling -1, -s, and -t. 

List times in full, rather than using the standard abbreviation heuristics. 

Ignored; for UN IX compati bility. 

Print the index number of each fileto theleft of thefilename. 

If filesizes are bei ng listed, printthem in kilobytes. Thisoverrides the environment vari able 

POSIXLY_CORRECT. 

In additi on to the name of each file, print the fi le type permissions, number of hard links, 
owner name, group name, sizein bytes, and timestamp (the modification time unless other 
times are sei ected). For files with a timethat is more than six monthsold or more than one 
hour into the future the timestamp contai ns the year instead of the ti me of day. 
List files horizontally, with asmanyaswill fiton each line, separated by commas. 
Listthe numeric U ID andGID instead of the names. 
Append acharacterto each filename indicatingthefiletype. 
Print question marks instead of nongraphic characters in filenames. 
Sort directory contents in reverse order. 

P ri nt the size of each filein 1KB blocksto the left of the filename. If the environment 

variableposixLY_coRRECT is set, 512-byteblocksareused instead. 

Sort directory contents by timestamp instead of al ph abeti cai ly, with the newest files listed 

first. 

Sort directory contents accordi ng to the files' last access time instead of the modification 
time. If the long listing format is bei ng used, print the last access time instead of the 
modification time. 
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-x, - -format=across, 
- -f ormat=horizontal 
-A, - -almost-all 
-B, - -ignore-backups 
-C, - -format=vertical 
-F, - -classify 

-G, - -no-group 
-L, - -deref erence 
-N, - -literal 
-Q, - -quote -name 
-R, - - recursive 
-S, - -sort=size 
-U, - -sort=none 



-X, - -sort=extension 

-1, - -format=single-coluinn 
-w, - -width cols 

-T, - -tabsize cols 
-I, - -ignore pattern 

- -help 
- -version 

BUGS 

On BSD systems, the-s option reportssizesthat arehalf the correct values forti lesthat are N FS-mounted tram H P-UX 
systems On HP-UX systems, it reportssizesthat are twice the correct values forti lesthat are N FS-mounted from BSD 
systems Thisisdueto aflaw in H P-UX; it also affects the H P-UX is program. 

GNU Fi le U ti liti es 

lsattr 

isattr— List file attri butes on a Linux second extended filesystem 
SYNOPSIS 

lsattr [ -Radv ] [ f i I es . . . ] 

D ESC RIFIO N 

isattr liststhefilesattributeson an second extended filesystem. 



List the files i n columns, sorted horizontally. 

Listali files in directories, exceptfor'.' and '. .'. 

Do notlist files that end with ", unlessthey aregi ven on thecommand line. 

List files in columns, sorted vertically. 

Append acharacter to each filmarne indicating the fi le type For regular files that are 

executable, append a *. Thefile type indicatore are / for directories, eforsymbolic links, | 

for FIFOs, = for sockets, and nothing for regular files. 

I nhi bit display ofgroup informati on in a long format directory listing. 

List the files linked to by symbolic links instead of listing the contentsof the links. 

Do not quote fi lenames. 

Enclose filenames in doublé quotes and quote nongraphiccharacters asin C. 
List the contents of ali di recto ri es recursi vely . 

Sort directory contents by fi le si ze instead of alphabetically, with the largest files listed first. 
D o not sort directory contents; list them in whatever order they are stored on the disk. This 
option is not called -t becausetheU N IX is -f option also enables -a and disables -1, -s, 
and -t. It seemsuselessand ugly to group thoseunrelated thingstogether in one option. 
Because this option doesn't do that, it hasadifferent name. 

Sort directory contents alphabetically by fi le extension (characters after the last period); files 
with no extension are sorted first. 
List onefile per line. 

Assume the se reen iscois columns wi de. The default istaken from the terminal driver if 
possi ble; otherwise, the environment vari able columns isused if it is set; otherwise, the 
default issa. 

Assume that each tab stop iscois columns wide The default iss. 
Do notlist fileswhosenames match the shel I pattern pattern unlessthey aregi ven on the 
command line. Asin theshell, an initial period (.) in afilenamedoes not match awildeard 

at the Start Of pattern. 

Printausagemessageon standard output and exit successfully. 
Print version information on standard output then exit successfully. 
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OPTIONS 

-R Recursively list attributes of di rectories and their contents. 

-a Listali fi les in di rectories, includi ng files that start with period (.). 

-d L ist di rectories I i ke other fi les, ratherthan listi ng their contents. 

-v Listthefilesversion. 

AUTHOR 

isattr hasbeen written by Remy Card (card@masi.ibp.fr), the deve! oper and maintainerof theext2 fs. 

BUGS 

There are none:-). 

AVAILABILITY 

Isattr isavailablefor anonymOUS FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs. 

SEEALSO 

chattr(l) 

Versi on 0.5b, N ovember 1994 

lsmod 

ismod— show the loaded modules 
SYNOPSIS 

lsmod 

D ESC RIFIO N 

ismod showsinformation aboutall loaded modules. The format is 

n a me s i z e [list o f referring mo d j I e s ] 

si ze isin 4Kb pages. 

This information is a copy of the contents of /proc/moduies. 
SEEALSO 

insmod(l), modprobe(l), depmod(l), rmmod(l), ksyms(l), modules(2) 

HI STORY 

Themodulesupport was first conceived byAnonymous (asfar asl know... ). Linux version by BasLaarhoven 
(basuvimec.m), 0.99.14 version byjon Tombs(jon@gtex02. us.es), extended by Bjom Ekwall (bj0rn@biox.se). 

BUGS 

ismod might havesome, but they arewell hidden.... 

Linux, 14 M ay 1995 
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ìynx— A general-purpose distri buted information browser for the World Wide Web 
SYNOPSIS 

lynx [opt i o n s ] [pat h or URL ] 

Use ìynx -heip to display a complete list of current options. 
D ESC RIFIO N 

ìynx is a fully-featured World Wide Web (WWW) eli ent for users running cursor-addressable, character-cell display devices 
(forexample, vtlOO termi nals, vtlOO emulators running on PC sor M acs, or any other "curses-oriented" display). Itwill 
display H ypertext M arkup Language(HTM L) documents contai ning linksto filesresidingon the locai system, aswell as 
filesresidingon remote systems running Gopher, HTTP, FTP, WAIS, and N NTP servers. Current versionsof ìynx run on 
UN IX and VMS. 

ìynx can beused to access information on the World Wide Web, orto build information systems intend ed pri mari ly for 
locai access. For example, ìynx hasbeen used to build several Campus Wide Information Systems (C W IS). In addition, ìynx 
can beusedto build systems i sol ated with in a si ngle LAN . 

OPTIONS 

At startup, ìynx will load any locai fi le or remote U RL specified at thecommand line. For help with U RLs, press? or n while 
running ìynx. Then follow the link ti ti ed "H elp on URLs." 

If theonly argument is -, then ìynx expeetsto receivetheargumentsfrom stdin.Thisisto allow 
for the potentially very longcommand linethat can beassociated with the -get_data or -postdata 
arguments. (See entri es for each later in thislist.) 
U sed to specify the anonymous account. 
D isable kanji code trans! ation when J apanese mode is on. 
Set authorization ID and password for protected documents at startup. 
Usethebookmark page as th e startf i I e. The default or command line startf i le is stili set for the 
M ain screen command, and will beused if thebookmark page isunavailableor blank. 
Toggles scanning of news articles for buried references, and convertsthem to news links Not 
recommended because e-mail addressesenclosed in angle brackets will be converted to false news 
links, and uuencoded messagescan be trashed. 
Set theNUMBER of documents cached in memory. The default is 1 0. 
E nable case- sensitive stri ng searching. 
Specifisaiynx confi guration file other than the default ìynx.cfg. 
Exiton left-arrow in star-mie, and disablesaveto disk. 

With -traversai, output each page to a file. With -dump, format output as with -traversai, butto 
stdout. 

Set the display variable for X rexeced programs. 

D umps the formatted output of the default document or one specified on the command line to 
standard out. Thiscan beused in thefollowingway: ìynx -dump http://www.w3.org/defauit.htmi. 
E nable Edit mode using the specified editor (vi, ed, emacs, and so on). 
Enable Emacs-like key movement. 

Toggle compati bi lity with comm programs' scrollback keys(may beincompatiblewith some 
packages). 

-error_fiie=Fi le D efi ne a file where ìynx will report HTTP accesscodes. 
-euc Set kanji codeto EUC when J apanese mode is on. 

-fiieversions Include al I versi ons of fi les in locai VM S directory listings. 

-torce htmi Forces the first document to beinterpreted asHTM L. 



-anonymous 
-ascii 

-auth=l D: PASS WD 
-book 

-buried news 



-cache=NUMBER 
-case 

-cfg=FI LENAME 

-child 

-crawl 

-dlsplay=DI SPLAY 
-dump 

-edltor=EDI TOR 
-emaeskeys 
-enable scrollback 



lynx 



-ftp 

-get_data 

-head 

-help 

-historical 

-homepage=URL 

-image_links 

-index=URL 

-jpn 

-link=UHB E R 
-localhost 
-locexec 

-mimejieader 

-minimal 

-nobrowse 

-noexec 

-nolist 

-nolog 

-noprint 

-noredir 

-nostatus 

-number_links 

-post_data 

-print 

-pseudo_inlines 

-realm 

-reload 

-restrictions=[option] 
[ .option] [ ,option] . . . 



DisableFTP access. 

Send form data from stdin using get method and dump results. 

Send a head request for the mi me headers. 

Print thisiynx command syntax usage message. 

Toggles use of > or -> as a termi nator for comments. 

Set home page separate from start page. 

Toggles inclusion of links for ali images. 

Set the default index file to thespecified URL. 

Toggles Japanesecharacter translati onson or off. 

Starti ng count for ink#.dat filesproduced by -crawl. 

D i sabl e U R L s that poi nt to rem ote h oste. 

Enable locai program execution from locai filesonly (if ìynx wascompiled with locai execution 
enabled). 

Pri nts the mime headerof afetched document alongwith itssource. 

Toggles minimal versus valid comment parsi ng. 

D i sabl e directory browsing. 

Disable locai program execution (default). 

D isablethe link listfeaturein dumps. 

D isable mailing of error messages to document owners. 

Disable print functions 

Preventsautomatic redirection and pri nts a message with a link to thenew URL. 
D isablethe retri eval status messages. 
Force numbering of links. 

Send form data from stdin using post method and dump results. 

E nable pri nt functi ons (default). 

Toggles pseudo-Ausfor inlineswith no alt string. 

Restricts access to URLs in the starting realm. 

Flushes the cache on a proxy server (only the first document affected). 

Allows a list of services to bedisabled selectively. The following list isprinted if no optionsare 

speci fi ed. 

ali— Restricts ali options. 

bookmark--D isallow changi ng the location of the bookmark file. 

bookmark_exec-D isallow execution links via the bookmark file. 

change_exec_perms— D isallow changing the execute permission on fi les (but stili allow it for 

directories) when locai file management is enabled. 

default -Same as command-li ne option -anonymous. D isables default services for anonymous users. 

Currently set tO ali restri Cted except for the following: insidetelnet, outside_telnet, inside_news, 
inside_ftp, outside_ftp, inside_rlbgin, butside_rlbgin, jump, mail, and gbto. D efaults are Settable 
within userdefs.h. 

dired„suppcrt— D isallow locai file management. 

disk_save— D isallow saving binary filesto disk in thedownload menu. 

downibad--D isallow downloaders i n thedownload menu. 

editor— D isallow editing. 

exec-D isable execution scripts. 

exec_frozen--D isallow theuserfrom changing the locai execution option. 
fiie_un--D isallow using goto to go to file: U RLs. 
goto— D isable the g (goto) command. 
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-rlogin 
-selective 
-show cursor 



-S]1S 

-source 
-telnet 
-term=TERM 



-trace 
-traversai 



-underscore 
-validate 



-vikeys 



COMMANDS 



inside_ftp— D isallow FTPsfor peoplecoming from inside your domain, (utmp required for 
selectivity.) 

inside_news— D isallow Usenet news posti ng for peoplecoming from inside your domain, (utmp 
required for selectivity.) 

inside_nogin— D isallow rlogins for people coming from inside your domain, (utmp required for 
selectivity.) 

inside_teinet-D isallow Tel netsfor people comi ng from inside your domain, (utmp required for 
selectivity.) 

jump— D isable the j (jump) command. 
maii-D isable mailing feature. 
news_post--D isable U senet news posting. 

options_save--D isallow Saving options in .lynxrc. 

outside_ftp— D isallow FTPsfor people coming from outside your domain, (utmp required for 
selectivity.) 

outside_news— D isallow Usenet news posting for people coming from outside your domain, (utmp 
required for selectivity.) 

outside_riogin— D isallow rloginsfor people coming from outsideyour domain, (utmp required for 
selectivity.) 

outside_teinet— D isallow Tel netsfor people comi ng from outsideyour domain, (utmp required for 
selectivity.) 

print— D isallow most print options. 

sheii— D isallow shell escapes and ìynxexec or ìynxprog goto's. 

suspend--D isallow UN IX C tri +Z suspendswith escape to sfidi. 

teinet_port— D isallow specifying a port in Telnet goto's. 

D isable recognition of riogin commands. 

Require .www browsable fi lesto browsedirectories. 

If enabled, the cursor wi II not behidden in theright-hand corner but will instead bepositioned at 

the start of thecurrently selected link. show_cursor is the default for systemswithout fancy_curses 

capabilities, and the default configuration can bechanged in userdefs.h. 

Set kanji codeto ShiftJISwhenJapanesemodeison. 

W orks the same as dump but outputs HTML source i nstead of formatted text. 

D isable recognition of Telnet commands. 

Teli ìynx what terminal typeto assume it'stalking to. (Thismay beuseful for remote execution 
when, for example, ìynx connectsto a remote TCP/IP port that starts a script that, in turn, starts 
another ìynx process.) 
Turnson WWW trace mode. 

Traverse ali HTTP links derived from startme. When used with -crawl, each link that begins 
with the same stri ng as startme is output to a file, intended for indexing. See crawl, announce for 
moreinformation. 

ToggleSUSeof_underline_format in dumps. 

Accept only HTTP U RLs (for validation). Complete security restrictions also areimplemented. 
Print version information. 
Enablevi-like key movement. 



UseU p arrow and Down arrow to serali through hypertext links. 
Right arrow or Return will follow a highlighted hypertext link. 
Left Arrow will retreatfrom a link. 



macptopbm 




■ Typeh or ? for online help and descriptionsof keystrokecommands. 

■ Type k for a complete list of the current keystroke command mappings. 

NOTES 

Thisis the Lynx 2.5 Releasefor U N *X/VM S. 

If you wish to contri buteto thefurther development of ìynx, subscribeto our mailing list. Send e-mail to majordomo@sig.net 
with "subscribelynx-dev" astheonlylineinthebody of your message. 

Send bug reports, comments, and suggestionsto ìynx-devfeig.net after subscribing. 

U nsubscribeby sending e-mail to majordomo@sig.net with unsubscribe ìynx-dev as theonly I ine in the body of your message. 
Do notsend the unsubscribe message to theiynx-dev list itself. 

ACKNOWLEDGMENTS 

ìynx has incorporated codefrom a variety of sources along the way. The earli est versionsof ìynx included codefrom E ari 
Fogel of Computing Servi cesat the U ni versi ty of Saskatchewan, who implemented hyperrez in the U N *X environment. 
hyperrez wasdeveloped by N iel Larson ofThink.com and served as the model for the early versionsof ìynx.Those versi ons 
also incorporated librariesfrom theU N*X Gopher clientsdeveloped at the U ni versi ty of M innesota, and the later versionsof 
ìynx rely on theWW W client library codedeveloped by Tim Berners- Lee and theWW W community. Also a special thanks 
to FoteosM acrides, who ported much of ìynx to VM S and to everyoneon the N et who has contri buted to ìynx's develop- 
ment either directly (through comments or bug reports) or indirectly (through inspiration and development of other 
systems). 

AUTHORS 

Lou M ontulli, Garrett Blythe, Craig Lavender, M ichael Grobe, Charles Rezac 
Academic Computing Services 
University of Kansas 
Lawrence, Kansas 66047 

Foteos M acrides 
Worcester Foundation 
Shrewsbury, M assachusetts 01545 

Locai 

macptopbm 

macptopbm— Con vert a M acPaintfile into a portable bitmap 
SYNOPSIS 

macptopbm [-extraskip N ] [ ma c p f i I e ] 

D ESC RIFIO N 

macptopbm reads a M acPaint file as input and produces a portable bitmap as output. 
OPTIONS 

-extraskip Thisflag isto get around a problem with some methodsof transferri ng fi lesfrom theM ac world to the 

UNIX world. M ost of these methods leavethe M acfiles alone, but a few of them add thetind-erinfo data 
onto the front of theU N IX file. Thismeansan extra 128 bytesto skip over when reading the fi le. The 
symptom to watch for isthat the resulti ng PBM filelooksshifted to oneside. If you get this, try - 
extraskip 128, and ifthat stili doesn'tlook right, try an other vai ue. 



Ali flags can be abbrevi ated to their shortest unique prefix. 
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SEEALSO 

picttoppm(l), pbmtomacp(l), pbm(5) 

AUTHOR 

Copyright © 1988 byjef Poskanzer. TheM acPaint-reading code is copyright© 1987 by Patri ckj. N aughton 

(naughton@wind . sun . com). 

29 M arch 1989 
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make— GNU make utility to maintain groups of programs 
SYNOPSIS 

make [ -f makef ile ] [ option ] ... target . . . 

WARNING 

Thisman pageisan extract of thedocumentation of GN U make. It isupdated only occasionali becausetheG N U project 
does not usenroff. For complete, current documentation, referto the info fi le make or the D VI filemake.dvi, which are 

madefrom thetexinfo SOUrcefilemake.texinfo. 

DESCRIPTION 

The purposeof the make utility isto determine automatically which piecesof a large program needto berecompiled, and 
issue the commands to recompilethem. Thismanual page describes the GN U implementation of make, which waswritten by 
Richard Stallman and Roland M cGrath. Our examplesshow C programs becausethey aremost common, but you can use 
make with any program mi ng languagewhose compi ler can berun with ashell command. In fact, make isnot limited to 
programs. You can useit to descri be any task wheresomefiles must beupdated automatically from otherswheneverthe 
others change. 

To prepare to use make, you must writeafilecalled the makef ile that describes the relationships amongfiles in your program 
and states the commandsforupdating each file. In a program, typically, the executable file isupdated from object files, 
which are in turn made by compilingsource files. 

0 ncea suitable makefile exi sts, each timeyou change some source files, thissimpleshell command: 
make 

sufficesto perform ali necessary recompilations. The make program uses the makef ne database and thelast-modification times 
of thefilesto decide which of the files need to beupdated. For each ofthose files, it issues the commands recorded in the 
database. 

make executes commands in the makefileto update one or more target names, where name is typically a program. If no -f 
option ispresent, make will look for the makefilesGNu-makef ile, makef ile, and Makefile, in that order. 

Normally you should cali your makefi le either makefile or Makefile. (Werecommend Makefile becauseit appearspromi- 
nently near thebeginningof a directory listi ng, right near other important files such asREADME.) T he first name checked, 
GNUmakefiie, isnot recommended for most makefi les. You should use this name if you have a makefi le that isspecific to 
GNU make, and will not beunderstood by other versi onsof make. If makefile is-, the standard input isread. 

make updates a target if it dependson prerequisite files that havebeen modified si nce the target was last modified, or if the 
target does not exi st. 
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OPTIONS 

-b, -m T hese options are ignored for compatibility with other versionsof make. 

-c di r Changeto directory di r before readingthemakefilesor doi ng anything else. If multi pie -c options are specifi ed, 
each isinterpreted relativeto thepreviousone: -c / -c etc is equivalere to -c /etc. T his is typically used with 
recursi ve i nvocations of make. 

-d Print debugging informati on in addition to normal processing. The debugging informati on sayswhich files are 
being considered for remaki ng, which filetimesare beingcompared and with what results, which files actually 
need to beremade, which implicit rules are considered and which areapplied— everything interesting about how 
make decides what to do. 

-e Givevariablestaken from the environment precedence over vari ablesfrom makefiles. 

-f file Usef i i e asamakefile. 

-i Ignoreall errorsin commandsexecuted to remake files. 

-i dir Specifiesa directory di r to search for included makefiles. Ifseveral -i options are used to speci fyseveral directo- 
ri es, thedirectoriesaresearched in theorder specified. U nliketheargumentsto other flags of make, directories 
given with -i flags may come di rectly after the flag: -idi r isallowed, aswell as-i di r . T his syntax isallowed for 
compatibility with theC preprocessor's-i flag. 

-j j o b s Specifi es the number of jobs(commands) to run simultaneously. If there ismorethan one-j option, thelast one 
iseffective. If the -j option is given withoutan argument, make will not I i mi t the number of jobsthat can run 
simultaneously. 

-k Continueasmuch as possi bl e after an error. Although the target that fai led, and thosethatdepend on it, cannot 

beremade, the other dependenciesof thesetargetscan beprocessed ali thesame. 
-ì, Specifi es that no new jobs(commands) should bestarted if there are other jobsrunning and theload averageisat 
-ì i o a d leastioad (a floating-poi nt number). W ith no argument, removes a previous load limit. 
-n Print the commands that would beexecuted, butdo not executethem. 

-o fi i e Do not remake the fi le file even if it isolder than itsdependencies, and do not remake anything becauseof 

changes in fi i e. Essentially, thefileistreated asvery old and its rules are ignored. 
-p Print the database (rules and variable values) that results from reading the makefiles; then executeas usuai oras 

otherwise specified. T his also prints the versi on informati on given by the-v switch (seebelow). To print the 

database withouttryingto remake any files, usemake -p -f/dev/nuii. 
-q Questi on mode. Do not run any commands or print anything; just return an exit status that is zero if the specified 

targets are al ready up-to-date, nonzero otherwise. 
-r E li mi nate use of the built-in implicit rules. Also clear out the default list of suffixesfor suffix rules. 
-s Silent operation; do notprintthecommandsastheyareexecuted. 

-s Cancel the effect of the-k option. Thisisnever necessary except in a recursi ve make where-k might beinherited 

from thetop-level make via makeflags or if you set -k in makeflags in your environment. 
-t Touch fi les (mark them up-to-date without really changingthem) instead of runningtheir commands. T his is 

used to pretend that the commands weredone, in orderto fool future invocationsof make. 
-v Print the versi on of the make program plus a copyright, a list of authors, and a notice that there is no warranty. 

After this informati on is printed, processing conti nuesnorm al ly. To get this informati on without doing anything 

else, use make -v -f/dev/nuii. 
-w Print a message contai ni ng the working directory before and after other processing. This may beuseful for 

trackingdown errorsfrom complicated nestsof recursivemake commands. 
-w file Pretend that the target file hasjustbeen modified. W hen used with the-n flag, thisshowsyou whatwould 

happen if you wereto modify that file. Without -n, it isalmost thesame asrunning a touch command on the 

given file before running make, except that the modification timeischanged only in the imagi nati on of make. 

SEE ALSO 

/usr/local/doc/gnumake.dvi 

TheGNU MakeManual 
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BUGS 

Seethechapter "Problemsand Bugs" inTheGN U M akeM anual. 
AUTHOR 

Thismanual page contri buted by DennisM orseof Stanford U ni versi ty. It hasbeen reworked by Roland M cGrath. 

G N U, 22 August 1989 
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makedepend— C reate dependencies in makefiles 
SYNOPSIS 

makedepend [ -Dname=def ][-Dname ] [-Iincludedir ] [ -Yincludedir ][-a ] 
[-fmakefile ] [-oobjsuffix ] [-pobjpref ix ][-sstring ][-wwidth ][-v ][-m ] 
[--otheroptions -- ] sourcefi I e . . . 



D ESC RIFIO N 

makedepend reads each sourcefi i e in sequenceand parsesit likea C-preprocessor, processing ali #inciude, #define, #undef, 
#ifdef, #ifndef, #endif, #if and #eise di recti ves so that it can correctly teli which #inciude, di recti veswould beused in a 
compilation. Any#inciude, directives can referencefileshavingother#inciude directives, and parsi ngwill occurin thesefiles 
aswell. 

E very fi le that a source fi le i ncludes, di rectly or i ndi rectly, is what makedepend cai Is a dependency. T hese dependenci es are then 
written to a makefile in such away that make(l) will know which object fi les must berecompiled when a dependency has 
changed. 

By default, makedepend places its output in thefile named makef ile if it exists; otherwise, Makefile. An alternate makefile may 
bespecified with the-f option. It first searches the makefile for the li ne 

# DO NOT DELETE THIS LINE -- make depend depends on it. 

or one provi ded with the-s option, as a del imi ter for the dependency output. If itfindsit, it will delete everything following 
thisto the end of the makefile and put the output after thisline If it doesn't find it, the program will append the stri ng to 
the end of the makefile and place the output following that. For each sourceme appearing on thecommand line makedepend 
putslinesin the makefile of theform: 

sourcefile.o: dfile . . . 

wheresourcefiie.o isthenamefrom thecommand li ne with itssuffix replaced with .0, and dfiie is a dependency 
discovered in a#inciude di rective whi le parsi ng s 0 j r c ef i 1 e oroneof thefilesit included. 

EXAMPLE 

Normally, makedepend will beused in a makefile target so that typing makedepend will bring the dependencies up-to-date for 
the makefile. Forexample, 

SRCS = filel .c file2.c . . . 
CFLAGS = -0 -DHACK -I . . /foobar -xyz 
depend: 

makedepend — $(CFLAGS) -- $(SRCS) 

OPTIONS 

makedepend will ignore any option that it does not understand so thatyou may use the samearguments that you would for 
cc(l). 



-Dname=det or Define. This places a definition for nane in makedepend's symbol table. Without =def, the symbol becomes 
-Dname defined as 1. 



makedepend 



-iinciudedir I nclude di rectory. T his option tei I s makedepend to prepend inciudedir to itslist of directoriesto search 
when itencountersa#inciude di rective By default, makedepend only searches the standard include 
directories (usually /usr/inciude and possibly a compi ler-dependent directory). 

-Yinciudedir Replaceall of thestandard include di rectorieswith the si ngle specifi ed i nclude directory; you can omitthe 
inciudedir to simply prevent searching thestandard include directories. 

-a Append thedependenciesto the end of the file i nstead of replacingthem. 

-fmakefiie Filmarne. Thisallowsyou to specify an alternate makefi le i n which makedepend can place its output. 

-oobjsuffix 0 bject file suffix. Somesystemsmay haveobjectfileswhosesuffix issomethingotherthan .0. T his option 
allowsyou to specify another suffix, such as .b with -o.b or :obj with -o:obj and so forth. 

-pobjprefix 0 bject file prefix. T he prefix isprepended to the nameof the object file. T his is usually used to designate a 
d i f f eren t directory for theobject file. T he default isthe empty string. 

-sstring Starting string delimiter. This option permitsyou to specify a different string for makedepend to look for in 

the makefi le. 

-wwidth Line width. N ormally, makedepend will ensurethat every output linethat itwriteswill beno widerthan 78 

charactersforthesake of readabi I ity. This opti on enablesyou to changethiswidth. 

-v Verbose operation. Thisoption causes makedepend to emit the list of filesincluded by each input file on 

standard output. 

-m Warn about multiple inclusion. Thisoption causes makedepend to produce a warning if any i nput file 

includes another file more than once. In previousversionsof makedepend, thiswas thedefault behavior; the 
default hasbeen changed to better match the behavior of the C compi ler, which doesnot consider 
multiple inclusion to bean errar. Thisoption is provi ded for backwards com pati bil ity, and to aid in 
debugging problems related to multiple inclusion. 

— options — If makedepend encounters a doublé hyphen (—) in the argument list, then any unrecognized argument 

following it will besilently ignored; a second doublé hyphen termi nates this special treatment. In thisway, 
makedepend can bemadeto safely ignoreesoteric compiler argumentsthat might normally befound in a 
cflags make macro. (See the precedi ng'Txample" section.) Ali options that makedepend recognizesand that 
appear between the pair of doublé hyphens are processed normally. 

ALGORITHM 

Theapproach used in this program enablesit to run an order of magnitudefaster than any other dependency generator I 
haveever seen. Central to th i sperform ance are two assumptions: that ali fi les compi led by a si ngle makefi le will be compi led 
with roughly thesame -i and -d options; and that most fi les i n a si ngle di rectory will include largely the samefi les. 

Given these assumptions, makedepend expectsto becalled once for each makefile, with ali source files that aremai ntai ned by 
the makefi le appearing on thecommand line. It parseseach source and include fi le exactly once mai ntai ni ng an internai 
symbol tablefor each. Thus, the first fileon thecommand li ne will take an amount of ti me proporti onal to theamount of 
timethatanormal C preprocessor takes. Buton subsequent files, if it encounters an include filethat it hasalready parsed, it 
doesnot parse itagain. 

Forexample, imagi neyou are compi ling two files, mei .c and me2.c; they both i nclude the header fi le header.h, and the 
file header.h in turn includes thefiles def 1 .h and def2.h. W hen you run thecommand: 

makedepend filel.c file2.c 

makedepend will parse f ilei .c and consequently, header.h and then defi .h and def2.h. It then decides that the dependencies 
for this file are 

filel.o: header.h def 1 . h def2.h 

Butwhen the program parsesme2.c and discoversthat it, too, includes header.h, it does not parse thefile, but simply adds 

header.h, defi .h, and def2.h tO the list Of dependencies for f ile2 .0. 

SEEALSO 



cc(l), make(l) 
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BUGS 

makedepend parses, but doesnot currently evaluate, the SVR4#predicate(token -list) preprocessor expression; such 
expressionsaresimply assumed to betrue. Thismay cause the wrong#inciude directi vesto beevaluated. 

Imagi ne you are parsi ng two files, say mei .c and fiie2.c, and each includesthefiledef.h. The list of filesthat def .h 
includes might truly bedifferentwhen def .h is included by mei .c than when it isincluded by me2.c. But when 
makedepend arrives at a list of dependencies fora file, it is cast in concrete. 

AUTHOR 

Todd Brunhoff, Tektronix, Inc. and M IT Project Athena 

X Versi on 11 Re!ease6 

makestrs 

makestrs— M ake stri ng table C sourceand header(s) 
SYNOPSIS 

makestrs [-f source] [-abioptions ...] 

D ESC RIFIO N 

The makestrs command creates stri ng table C source files and headers. If -f source isnotspecified, makestrs will read from 
stdin. TheC source file isalwayswritten to stdout. makestrs creates one or moreC header files as specified in the source fi le. 

Thefollowingoptionsmaybespecified: -sparcabi, -intelabi, -functionabi, -arrayperabi, and -defaultabi. 

-sparcabi isused on SPARC platformsconformingtotheSPARC C ompliance D efinition, i.e, SVR4/Solaris. 

■intelabi used on Intel platformsconforming to the System V Application Binary Interface (SVR4). 

-eariyR6abi may beused in addition to -intelabi for situationswherethevendorwishesto maintain binary compati bility 
between X11R6 public-patch 11 (and earlier) and X11R6 public-patch 12 (and later). 

-tunctionabi generates a functional application binary interfaceto the stri ng table. Thismechanism imposes a severe 
performance penalty and it's recommended that you not use it. 

-arrayperabi results in a separate array for each stri ng. Thisis the default behavior if makestrs wascompiled with - 
darrayperstr (it almost never is). 

-defaultabi forces the generation of the"normal" stri ng table even if makestrs wascompiled with -darrayperstr. makestrs is 
almost never compi led with -darrayperstr, so thisis the default behavior if no application binary interface (ABI) opti ons are 
specified. 

SYNTAX 

Thesyntax for string-list file is as follows (items in square brackets are o pti o n al ) : 

#prefix <text> 
#feature <text> 
#externref <text> 
#externdef [<text>] 
[#ctempl <text>] 
#file <filename> 
#table <tablename> 
[#htempl] <text> 

<text> 

[#table <tablename> 
<text> 



mattrib 




<text> 

#table <tablename> 
...] 

[#file <filename> 
...] 

You may haveoneor more #f ile di rectives. Each #me may haveoneor more#tabie directi ves. 
The#prefix directivedeterminesthestringthatmakestrwill prefixto each definition. 

The#feature directive determines the stri ng that makestr will useforthefeature-test macro, forexample, x-stringdefines. 
The#externref directive determinesthestring that makestr will use for the extern clause; typically thiswill be extern, but 

M Otif wantsittO beexternalref. 

The#externdef directive determinesthestring that makestr will useforthedeclaration; typically, thiswill be the nuli stri ng, 

and M Otif will USeexternaldef (_xmstrings) . 

The#ctmpi di recti ve determines the nameof the file used asatemplatefortheC source fi le that is generate! 

Each #tiie <f i i e n a me > di recti ve will result in acorrespondingheader file by that name contai ning the appropriate defini ti ons 
asspecified by command-lineoptions. A single C source fi le contai ning the declarations for the defini ti ons in ali theheaders 
will beprinted to stdout. 

The #ntmpi di recti ve determi nes the name of the fi le used as a tempi ate for the C header fi le that is generated. 

Each #tabie <tabi ename> directivewill be processed in accordancewith the ABI. On most platforms, ali tableswill be 
catenated into asingletablewith the nameof the first table for that file. To conform to the Intel ABI, separate tableswill be 
generated with the names indicated. 

The tem pi ate fi I es speci fi ed by the#ctmpi and #htmpi di recti ves are processed by copying li ne for linefrom thetemplatefile 
to the appropriate output file. The li ne contai ning the stri ng «<string_table_goes_here»> isnot copied to the output file. 
The appropriate data isthen copied to the output fi le and then the remainder of the template fi le is copied to the output file 

BUGS 

makestrs is not very forgi vi ng of syntax errors. Sometimesyou need atrailing space after # di recti ves, other times they wi II 
messyou up. N o warning messagesareemitted. 

SEEALSO 

SPARC Compliance Definition 2.2, SPARC International Inc., 535 M iddlefield Road, Suite 210, M enlo Park, CA 94025 

System V Application Binary Interface, Third Edition, ISBN 0-13-100439-5, U N IX Press, PTR Prentice H ali, 113 Sylvan 
Avenue, Englewood Cliffs, NJ 07632 

System V Application Binary Interface, Third Edition, Intel386 Architecture Processor Supplement, ISBN 0-13-104670-5, 
UNIX Press, PTR Prentice Hall, 113 Sylvan Avenue Englewood Cliffs, NJ 07632 

System V Application Binary Interface, Third Edition, SPARC Architecture Processor Supplement, ISBN 0-13-104696-9, 
UNIX Press, PTR Prentice Hall, 113 Sylvan Avenue Englewood Cliffs, NJ 07632 

X Version 11 Release6 

mattrib 

mattrib— C hange M S-D O S file attribute flags 



SYN0PSIS 

mattrib [ -a|+a ][-h|+h ][-r|+r ][-s|+s ] msdosfile [ msdosfiles. . . ] 
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D ESC RIFIO N 

mattrib adds attri bute flags to an M S-D 0 S file (with the+ operatori or removesattributeflags (with the - operator). 

mattrib allows thefollowing com mand-l ine opti ons: 

a Archivebit. Used by somebackup programsto indicate a new file. 

r Read-only bit. Used to indicate a read-only file Fileswith thisbit set cannot beerased by del or modified. 

s System bit. Used by M S-D 0 Sto indicatean operating system file, 

h H idden bit. Used to makefiles hidden from dir. 

SEEALSO 

mtools(l) 

Locai 

mbadblocks 

mbadbiocks— Scan an M S-D 0 S floppy and mark its unused bad blocks as bad. 
SYNOPSIS 

mbadblocks drive: 

D ESC RIPTIO N 

mbadblocks scansan M S-D OS floppy for bad blocks. Ali unused bad blocks are marked assuch in theFAT. Thisisintended 
to beused ri ght after mformat. It isnot intended to salvagebad disks 

SEEALSO 

mtools(l) 

BUGS 

Thisshould (but doesn't :-( ) also try to salvagebad blocks that are in useby readingthem repeatedly, and then mark them 
bad. 

mcd 

mcd— C hange M S-D O S directory 
SYNOPSIS 

mcd [ msdosdirectory ] 

DESCRIPTION 

Without arguments, mcd will report the current device and working directory. Otherwise, mcd changes the current device and 
current worki ng directory relative to an M S-D 0 S fi lesystem. 

T he envi rammentai variable mcwd may beused to locate the fi le where the devi ce and current working directory informati on is 
stored. The default is$HOME/.mcwd. Information in thisfileisignored if thefileismorethan sixhoursold. 

M S-D OS subdirectory namesaresupported with either the / or \ separator. The use of the \ separatororwildcardswill 
req u i re t h e d i recto ry nameto beenclosed in quotesto protect itfrom theshell. 

mcd returns 0 on success or 1 on fai Iure. 



SEEALSO 

mdir(l) 



mcopy 



BUGS 

U nlike M S-DOS versi onsof CD, mcd can beused to changeto another device 
It may bewiseto removeold .mcwd filesat logout. 

Locai 



mcookie 

mcookie— Generate magic cookies for xauth 
SYNOPSIS 

mcookie 

D ESC RIFIO N 

mcookie generates a 128-bit random hexadecimal numberforusewith theX authority system. Typical usage: 

xauth add :0 . 'mcookie 

SEEALSO 

X(l), xauth(l) 

12 February 1995 



mcopy 

mcopy— Copy MS-DOS filesto/from UNIX 
SYNOPSIS 

mcopy [ -tnvmoOsSrRA ] sourcefi I e targetfile 

mcopy [ -tnvmoOsSrRA ] sourcefile [ sourcefi I es . .. ] targetdi rectory 
mcopy [ -tnvm ] MSDOSsourcefi I e 



DESCRIPTION 

mcopy copiesthespecified fileto thenamed file, or copies multiple filesto thenamed directory. Thesourceand target can be 
eitherMS-DOSorUNIX files. 

The use of a drive letter design ation on theM S-DOS files— a: for example— determi nes the direction of the transfer. A 
mi ssing drive desi gnation impliesaU N IX filewhosepath startsin thecurrent directory. If a source drive letter isspecified 
with no attached filmarne (for example, mcopy a: .), ali files are copied from that drive. 

If only a single, M S-D OS source parameter is provi ded (for example, mcopy a:foo.exe), an implied destination of thecurrent 
directory).) isassumed. 

A filenameof - meansstandard input or standard output, dependi ng on its position on thecommand line, 
mcopy wi II allow thefollowing command-lineoptions: 

t Text fi le transfer, mcopy will translate incoming carriage return/li nefeads to linefeeds. 

n N o warning. mcopy will notwarn the user when overwriting an existing file. 

v Verbose mode. 

m Preservethefile modification time 

If the target filealready exists, and the -n option isnot in effect, mcopy askswhether to overwritethefileor to renarne the new 
file. (Seethemtoois(l) man page for details.) 
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SEEALSO 

mtools(l), mread(l), mwrite(l) 

BUGS 

UnlikeM S-DOS, the+ operator (append) from M S-DOS isnot supportai. 

Locai 

md5sum 

md5sum— Generate/check M D 5 messagedigests 
SYNOPSIS 

md5sum [-bv] [-c [ file ] ] 
md5sum file . . . 

D ESC RIPTIO N 

md5sum generates and checksM D5 messagedigests, asdescribed in R FC -1321. The message digest produced can bethought 
ofas a 128-bit "signature" of the input file. Typically, mdssum isused to verify the integri ty of files madeavailablefor 
distri bution viaanonymous FTP (for example, announcementsfor new versi onsof irc(l) usually contai n M D5 signatures). 
M essagedigestsfor a treeof files can begenerated with a command similarto thefollowing: 

find . -type f -print | xargs mdSsum 

The output of this command is suitableas input for the -c option. 
OPTIONS 

-c [file] Check messagedigests. Input istaken from stdin or from the specified file. The input should bein the 

same format as the output generated by mdssum. 
-v Verbose. Print filenameswhen checking. 

-b Readfilesin binary mode otherwise, end-of-fi leconventions will beignored. 

HISTORY 

Themd5sum program waswritten by Branko Lankester and may befreely distri buted. The originai sourcecodeisin theM IT 
PGP 2.6.2 distri bution. Thoseconcerned about the integri ty of thisversion should obtain the originai sourcesand compile 
theirown version. 

Theunderlying implementation of Ron Rivest'sM D 5 algorithm waswritten by Colin Plumb and is in the public domain. 
(Equivalent code isalso availablefrom RSA D ata Security, Inc.) 

SEEALSO 

sum(l), cksum(l), pgp(l) 

Linux 1.0, 11 February 1995 



mdel 

mdei- Delete an M S-DOS file 
SYNOPSIS 



mdel [ -v ] msdosfile [ msdosfiles... ] 



mdi 



D ESC RIFIO N 

mdei deletesafileon an M S-DOSfilesystem. 

radei will allow thefollowing command-lineoption: 

v Verbosemode. Echothefilenamesastheyareprocessed. 

mdei will ask for verification prior to removi ng a read-only file. 

SEEALSO 

mtools(l) 

Locai 

mdeltree 

mdeitree— Remove an M S-D 0 S di rectory tree 
SYNOPSIS 

mdeltree [ -v ] msdosdi rectory [ ms dosdi r ect or i es . . . ] 

D ESC RIFIO N 

mdeltree removes a directory and ali thefilesand subdirectoriesit contai nsfrom an M S-DOSfilesystem. mdeltree will allow 
thefollowing command-lineoption: 

v Verbose mode. D isplayseach fileor directory as it isremoved. 

An error occurs if the directory does not exist. 

SEEALSO 

mtools(l), mrd(l) 

Locai 

mdir 

mdir— D isplay an MS-DOS directory 
SYNOPSIS 

mdir [ -w ] msdosdi rectory 

mdir [ -w ][-a ] msdosfile [ msdosfiles... ] 

D ESC Rimo N 

mdir displaysthecontentsof an MS-DOS directory, 
mdir will allow the followi ng command-lineoptions 

w W i de output. Thisoption will printthefilenamesacrossthepagewithout displaying the file size or creati on date, 

a Also list hidden files. 

An error occurs if a component of the path is not a di rectory. 
SEEALSO 

mtools(l) 

Locai 
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merge 

merge— T h ree-way fi I e merge 
SYNOPSIS 

merge [ opti o n s ] filel f i I e 2 f i I e 3 

D ESC RIFIO N 

merge incorporates ali changesthat lead from f i i e 2 to f i 1 e 3 into fi 1 e 1 . T he result ordì nari ly goes i nto fi 1 e 1 . merge isuseful 
for combini ng separate changesto an originai. Supposef 1 e 2 is the originai, and both f m e 1 and f i e 3 aremodificationsof 
fi 1 e2.Then merge combinesboth changes. 

A conflict occurs if both fi lei and f 1 e 3 have changes in a common segment of lines. If a confi ict isfound, merge normally 
outputsa warningand brackets the conflict with «««< and »»»> lines. A typical confi ict wi II look likethis: 

«««< f i I e A 
lines in file A 



lines in file B 
»»»> file B 

If there are conflicts, the user should edit the result and delete one of the alternatives. 
OPTIONS 

-a Output conflicts using the-A styleof diff3(l), ifsupported by diff3. This merges ali changes leading from fiie2 

to tiie3 into fiiei, and generates the most verbose output. 
-e, -e Theseoptionsspecify conflict stylesthat generate less information than -a. Seedìff3(l) for detai Is. T he default is 

-e. W ith -e, merge does not warn about conflicts. 
-l 1 abei Thisoption may begiven up to threetimes, and specifies labels to beused in place of the corresponding fi lenames 

in conflict reports. That is, merge-Lx-L y -lz a b c generates output that looks likeit camefrom filesx, y, and z 

instead of from fi lesa, t>, and c. 
-p Send resultsto standard output instead of overwritingfiiei. 
-q Quiet; do not warn about conflicts. 
-v Print RCS's version number. 

DIAGNOSTICS 

Exit status isa for no conflicts, 1 for some conflicts, 2 fortrouble. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.7; Release D ate: 1995/06/01. 
Copyright © 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 

SEEALSO 

diff3(l), diff(l), rcsmerge(l), co(l) 

BUGS 

It normally does not makesenseto merge bi nary fi lesas if they weretext, but merge triesto do it anyway. 

GNU, 1 Junel995 
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mesg 

mesg— Display (do not display) messagesfrom otherusers 
SYNOPSIS 

mesg [n][y] 

D ESC RIFIO N 

The mesg utility isinvoked by ausersto control write access othershaveto the terminal devi ce associ ated with the standard 
errar output. If write access isallowed, then programssuch astaik(l) and write(l) may display messageson the terminal. 

Traditionally, write access isallowed by default. H owever, asusers become more consci ousof varioussecurity risks, there isa 
trend to remove write access by default, at least for the primary login shell. To makesureyourttys are set the way you want 
them to beset, mesg should beexecuted in your login scripts. 

0 ptions available: 

n D isallows messages 

y Permits messages to bedisplayed 

If no argumentsaregiven, mesg displaysthepresent messagestatusto the standard errar output. 
Themesg utility exitswith oneof thefollowing values: 
\0 M essagesareallowed. 
M M essages are not allowed. 

1 An errar hasoccurred. 

FILES 

/dev/[pt]ty[pq]? 

SEEALSO 

biff(l), talk(l), write(l), wall(l), login(l), xterm(l) 

HI STORY 

A mesg command appeared in version 6 AT&T U N IX. 

Linux 1.2, 10 March 1995 



mformat 

mformat— Add an M S-D OSfilesystem to a low-level formatted disk 
SYNOPSIS 

mformat [ -t tracks ] [ -h heads ] [ -s sectors ] [ -1 volume label ] 
[ -S sizecode ] [ -2 sectors on track 0 ] [ -M software sector size ] 
[ -a ][-X ][-C ][-H hidden sectors ] drive: 

D ESC RIFIO N 

mformat adds a minimal M S-D OSfilesystem (boot sector, FAT, and root directory) to a disk that hasalready been formatted 
by a U N IX low-level format. 

Thefollow opti ons are supported: (Thes, 2, 1, and m opti ons may not exist if thiscopy of mtoois hasbeen compi led without 
theusE_2M option). 
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t The number of tracks(not cylinders). 

h Thenumberof heads(sides). 

s Thenumberof sectors per track. If the2m option isgiven, number of 512-bytesector equivalentson generic tracks 

(that is, not head 0 track). I f the 2m option isnot given, number of physi cai sectors per track (which may bebigger 
than 512 bytes). 

1 An optional volume label. 

s Thesizecode Thesizeof thesector ÌS2 - (sizecode + 7). 

2 2m format. The parameterto this option describes the number of sectors on track 0, head 0. This option is 
recommended for sectors bigger than normal. 

1 D on't use a 2m format, even ifthecurrentgeometryofthediskisa2mgeometry. 

m Software sector size. T his parameter describes the sector size in bytes used by the MS-DOS fi lesystem. By default 

it i s the physical sector size. 

a If this option isgiven, an Atari-style serial number isgenerated. Atarisstoretheir serial number in theOEM label, 

x Formats the disk asan Xdf disk. Xdf disks are used byOS/2. Thisformat can hold 1756Kb, and is faster than the 

equivalent 2m formats. Thedisk hasfirstto below-level formatted usingthexdfcopy utility included in thetdums 

package 

c Creates the disk imagefileto instali theM S-DOSfilesystem on it. Obviously, thisisuselesson physical devices 

such as floppies and hard disk partitions. 

h N umber of hidden sectors. This parameter isuseful forformatting hard disk partitions, which are not aligned on 

track boundaries (in other words, first head of first track doesn't belongto the partition, but contai ns a partiti on 
table). In that case the number of hidden sectors is in general the number of sectors per cylinder. Thisisuntested. 

n Serial number. 

To format a disk at a density other than the default, you must supply (at least) thosecommand-lineparametersthatare 
different from the default. 

Mformat returnso on success or 1 on failure. 
SEEALSO 

mlabel(l) 

BUGS 

Requiresalow-level format utility from UN IX. 
D oesn't detect (or record) bad block information. 

Locai 

mgrtopbm 

mgrtopbm— Convertan MGR bitmap into a portable bitmap 
SYNOPSIS 

mgrtopbm [ mg r f i I e ] 

D ESC RIFIO N 

mgrtopbm readsan MGR bitmap as input and produces a portable bitmap as output. 
SEEALSO 

pbmtomgr(l), pbm(5) 



mkfifo 323 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

24 January 1989 

mkdir 

mkdii — M akedirectories 
SYNOPSIS 

mkdir [-p] [-m mode] [--parents] [ - -mode=mode] [--help] [--version] dir... 

DESCRIPTION 

This manual page documents the GN U version of mkdir. mkdir creates a directory with each given name. By default, the 
modeof created directories is 0777 minusthe bitsset in theumask. 

0PTI0NS 

-m, --mode mode Set the mode of created di rectories to mode, which is symbolic as in chmod and uses the default mode as the 
pointof departure. 

-p, - parents Ensurethat each given directory exists. Create any missing parent directoriesfor each argument. Parent 
directories default to theumask modified by u+wx. Do not consider an argument directory thatalready 
exists to bean errar, 
-heip Printausagemessageon standard output and exitsuccessfully. 

--version Print version information on standard output then exitsuccessfully. 

GNU Fi le U ti liti es 

mkdirhier 

mkdirhier— M ake a directory hierarchy 
SYNOPSIS 

mkdirhier directory ... 

DESCRIPTION 

Themkdirhier command creates the specified directories. Unlike mkdir, if any of the parent directories of the specified 
directory do notexist, it creates them aswell. 

SEEALSO 

mkdir(l) 

X Version 11 Release6 

mkfifo 

mkfifo— M akeFIFOs(named pipes) 
SYNOPSIS 

mkfifo [-m mode] [ - -mode=mode] [--help] [--version] filename... 
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D ESC RIFIO N 

Thismanual page documents the GN U version of mkfifo. mkfifo createsa FIFO with each given name. By default, the mode 
of created FIFOs is 0666 minus the bitsset in theumask. 

OPTIONS 

-m, --mode mode Set the mode of created FI FO s to mode , which is symbolic as in cnmod and uses the default mode as the 
pointof departure. 

-heip Printausagemessageon standard output and exitsuccessfully. 

--version Printversion information on standard output then exitsuccessfully. 

GNU F i le U ti I i ti es 

mkmanif est 

mkmanifest— Create a shell script to restoreUNIX filenames 
SYNOPSIS 

mkmanifest [ f i I es ] 

D ESC RIFIO N 

mkmanifest creates a shell script thatwi II aid in therestoration of U N IX filenamesthat got clobbered by theM S-D OS 

fi lename restri ctions. M S-D OS filenames are restricted to eight-character names, three-character extensions, uppercaseonly, 

no device names, and no illegal characters. 

The mkmanifest program iscom pati ble with themethodsused in pcomm, are, and mtoois to change perfectly good UNIX 
filenames to fit theM S-D OS restri ctions. 

EXAMPLE 

Say you want to copy the following U N IX fi lesto an M S-D OS disk (using themeopy command): 

very_long_name 

2.many.dots 

illegal: 

good.c 

prn.dev 

Capital 

meopy will convert the names to 

very_lon 

2xmany.dot 

illegalx 

good.c 

xprn.dev 

capital 

Thecommand: 

mkmanifest very_long_name 2.many.dots illegal: good.c prn.dev Capital > manifest 

would produce the following: 

mv very_lon very_long_name 
mv 2xmany.dot 2.many.dots 
mv illegalx illegal: 
mv xprn.dev prn.dev 
mv capital Capital 
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N oticethatgood.c did not requireany conversion, so it did not appear in the output. 

Suppose l've copi ed thesefilesfrom the disk to another UNIX system, and I now want the fi les back to their originai names. 
If the file manif est (the output captured above) wassent along with thosefiles, it could beused to convert thefilenames. 

BUGS 

The short names generated by mkmanìfest follow the old convention (from mtoois-2.0.7) and nottheonefrom Windows95 
and mtoois-3.0. 

SEEALSO 

arc(l), pcomm(l), mtools(l) 

Locai 

mknod 

mknod— M ake special fi les 
SYNOPSIS 

mknod [options] filename {bcu} major minor 
mknod [options] filename p 

Options: 

[-m mode] [ - -mode=mode] [--help] [--version] 

D ESC RIFIO N 

Thismanual page documents the GN U version of mknod. mknod createsa FIFO, character special file, or block special fi le with 
thegiven filename. By default, the mode of created fi les is 0666 minusthe bits set in theumask. 

T he argument after filename speci fi es the type of fileto make: 

pforaFIFO 

b for a block (buffered) special file 

c or u for a character (unbuffered) special file 

When making a block or character special file, the major and minor device numbers must begiven after the fi le type. 
OPTIONS 

-m, --mode mode Set the mode of created files to mode , which issymbolic as in cnmod and uses the default mode as the poi nt 
of departure. 

-heip Printausagemessageon standard output and exit successfully. 

--version Print version information on standard output then exit successfully. 

GNU F i le U ti I i ti es 

mlabel 

miabei— M ake an M S- D 0 S voi um e I abel 
SYNOPSIS 

mlabel [ -v ] drive: [ n e w_ I abel ] 
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D ESC RIFIO N 

miabei displays the current volume label, if present. If ne w_ i a b e i isnot given, and if neither thec northes optionsareset, it 
prompts the user for a new volume label. To delete an existing volume label, press return attheprompt. 

miabei supports thefollowing command-lineoption: 

v Verbose mode. Display the new volume label if the label supplied isinvalid. 

c Clearsan existing label, without prompting the user, 

s Shows the existing label, without prompting the user. 

Reasonablecareistaken to createavalid M S-D OS volume label. If an invalid label isspecified, miabei will eh ange the label 
(and display the new label if the verbose mode is set). 

Miabei returnsa on success or 1 on fai Iure. 
SEEALSO 

mformat(l) 

Locai 

mmd 

mmd— M ake an MS-DOS subdirectory 
SYNOPSIS 

mmd [ -voOsSrRA ] msdosdi rectory [ msdosdi r ect or i es . . . ] 

D ESC RIFIO N 

mmd makesa new directory on an M S-DOSfilesystem. 

mmd will allow thefollowi ng command-lineoption: 

v Verbose mode. D isplay the new directory nameasit iscreated. 

An errar occurs if the directory al ready exists. 

SEEALSO 

mtools(l), mrd(l), 

Locai 

mmount 

mmount— M ount an M S-D 0 S di sk 
SYNOPSIS 

mmount msdosdrive [mountargs] 

D ESC RI FIO N 

mmount reads the boot sector of an M S-D OS disk, configures the drive geometry, and finally mountsit, passi ng mountargs to 
mount. If no mount argumentsarespecified, the nameof the device isused. If the disk iswrite-protected, it is automati cally 
mounted read-only. 
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SEEALSO 

mtools(l), mount(8) 

Locai 



mmove 

mmove— M ove or renarne an existi ng M S-D 0 S fi le or subdi rectory 
SYNOPSIS 

ramove [ -voOsSrRA ] sourcefi I e targetfi I e 

mmove [ -voOsSrRA ] sourcefile [ sourcefiles. . . ] targetdirectory 

D ESC RIFIO N 

mmove movesor renamesan existing M S-D OS fi le or subdi rectory. 
mmove will allow thefollowing command-lineoption: 

v Verbosemode. Display the newfilenameif thenamesupplied isinvalid. 

Additi onally, it allows the clash-handli ng options described in the man pageformtoois. 

M S-D OS subdi rectory namesaresupported with either the / or \ separator. The use of the \ separator or wi Idcards wi II 
requirethenamesto beenclosed in quotesto protect them from theshell. U nlike the M S-D OS version of move, mmove isable 
to move subdi recto ri es. 

SEEALSO 

mren(l), mtools(l) 



more 

more— File perusal fi Iter for crt viewing 
SYNOPSIS 

more [-dlfpcsu] [-num] [+/ pattern] [+ linenum] 

D ESC RIFIO N 

more is a fi Iter for paging through text onescreenful at a ti me. T hi s version isespecially primitive. Usersshould realizethat 
iess(l) providesmore(l) emulation and extensiveenhancements. 

OPTIONS 

Command-lineoptions are described in thefollowing list. Options are also taken from theenvironment vari ableMORE (make 
sureto precede them with a hyphen (-)) but command-lineoptionswill overridethem. 

-num Thisoption specifiesan integer that is the screen size {i n lines). 

-d more Will prompttheuserwith themessage [Press space to continue, 'q 1 to quit.] and will display [Press 'h 1 

for instructions.] instead of ringing the beli when an illegal key is pressed. 
-ì more usually treats (form feed) as a special character, and will pause after any linethatcontainsaform feed. The -1 

option will prevent this behavior. 
-f Causesmore to count logicai, ratherthan screen lines (that is, long lines are notfolded). 
-p Do not serali. Instead, clear the whole screen and then display the text. 

-c Do not serali. Instead, paint each screen from the top, clearing the remainder of each lineasit isdisplayed. 
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-s Squeeze multiple blank lines into one. 

-u Suppressunderlining. 

+/ The+/ option specifies a string that will besearched for beforeeach fi le is displayed. 

+num Startatlinenumber. 

COMMANDS 

Interactive commands for more arebased on vi(l). Some commands may bepreceded by a decimai number, called k in the 
following descri ptions. In the followi ng descri ptions, *x meanscontroi-x. 

hor? Help: display a summary of these commands. If you forget ali the other commands, rememberthisone. 

space D isplay next k lines of text. D efaultsto current screen size. 

z D isplay next k lines of text. D efaultsto current screen size. Argument becomes new default. 

return D isplay next k lines of text. D efaultsto 1. Argument becomes new default. 

d or "d Scroll k lines. D efault is current serali size, initially 11. Argument becomes new default. 

q Or Q INTERRUPT Exit. 

s Skipforward k lines of text. D efaultsto 1. 

f Skipforward kscreenfulsof text. D efaultsto 1. 

b or "b Skip backwards k screenfulsof text. D efaultsto 1. 

Go to placewhere previ oussearch started. 

D isplay current line number. 
/pattern Search for kth occurrenceof regular expression. D efaultsto 1. 

n Search for kth occurrence of last r.e. D efaults to 1 . 

!<cmd>or :!<cmd> Execute <cmd> in a subshell. 
v Start up /usr/bin/vi at current line 

"l Redraw screen. 

:n G o to kth next file. D efaults to 1 . 

:p Go to kth previ ous fi le. D efaultsto 1. 

ic :t Display current fi lename and linenumber. 

Repeat previouscommand. 

ENVIRONMENT 

more uti I izes the fol lowi ng environment variables, if they exist: 
more Thisvariablemay besetwith favored optionsto more. 
shell Current shell in use(normally set bytheshell at login time). 

term Specifies terminal type, used by more to get the terminal characteristics necessary to manipulatethescreen. 
SEEALSO 

vi(l), less(l) 

AUTHORS 

Eric Shienbrood, UC Berkeley. M odified by Geoff Peck, UCB to add underlining, single spaci ng. M odified byjohn 
Foderaro, UCB to add -e and more environment variable 

HI STORY 

The more command appeared in BSD 3.0. This man page documents more version 5.19 (Berkeley 29 Junel988), which is 
currently in use in the Linux community. D ocumentation wasproduced usingseveral other versi onsof the man page, and 
extensiveinspection of thesourcecode 

Linux 0.98, 25 December 1992 
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mrd 

mrd— Remove an M S-D OS subdirectory 
SYNOPSIS 

mrd [ -v ] msdosdirectory [ msdosdirectories. . . ] 

D ESC RIPTIO N 

mrd removes a directory fra m an M S-D OSfilesystem. mmd will allow thefollowing command-l ine opti on: 
v Verbosemode. D isplay the directory nameasit isremoved. 

An errar occurs if the directory does not exist or is not empty. 

SEEALSO 

mtools(l), mmd(l), mdeltree(l) 

Locai 

mread 

mread-Read (copy) an M S-D OS fi le to UN IX 
SYNOPSIS 

mread [ -tnvmoOsSrRA ] msdosfile uni x f i I e 

mread [ -tnvmoOsSrRA ] msdosf il e [ msdosftles ... ] uni xdi rectory 

DESCRIPTION 

Thiscommand is obsolete, and only supplied for backwards compati bility reasonswith old scripts. Usemcopy instead. 
SEEALSO 

mcopy(l), mtype(l), mtools(l) 

mren 

mren— Renarne or movean existing M S-D OS fi le or subdirectory 
SYNOPSIS 

mren [ -voOsSrRA ] sourcefi I e targetfile 

mmove [ -voOsSrRA ] sourcefile [ sourcefiles. . . ] targetdirectory 

DESCRIPTION 

mren renamesan existing file on an M S-D OS filesystem. 
Mren will allow the followi ng command-lineoption: 

voossrRA Verbosemode. D isplay the newfilenameif the name supplied isinvalid. 

If the first syntaxisused (only one sourcefile), and if the target name doesn't contain any slashes or colons, the file (or 
subdirectory) will berenamed in the same di rectory, instead of being moved to thecurrent mcd directory aswould be the case 
with mmove. U ni i ke the M S-D 0 S version of ren, mren can beused to renarne di rectories. 
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BUGS 

U nlike the M S-DOS version of ren, mren can beused to renarne di rectories. 
SEEALSO 

mcd(l) 

Locai 

mtest 

mtest— Test the mtoois conf i gurati on files 
SYNOPSIS 

mtest 

D ESC RIFIO N 

mtest reads the mtoois configuration files and prints the cumulati veconfiguration to stdout. The output can beused asa 
confi guration fileitself (although you might want to remove redundant clauses). You may use this program to convert old- 
style configuration files into new style configuration files. 

SEEALSO 

mtools(5) 

Locai 

mtoois 

mtoois— A col lection of toolsfor manipulating M S-DOS files 

SYNOPSIS 

The mtoois are 

mattrib— C hange M S-D 0 S file attribute flags 

mbadbiocks— Test a floppy disk, and mark thebad blocksin theFAT 

mcd— C hange M S-D 0 S directory 

mcopy- C opy MS-DOS files to/from UNIX 

mdei- Delete an M S-D OS file 

mdir— D isplay an MS-DOS directory 

mformat— Add an M S-D OSfilesystem to a low-level formatted floppy disk 

miabei— M akean M S-DOSvolumelabe! 

mmd— M ake an MS-DOS subdirectory 

mmount— Mount an MS-DOS disk 

mrd— Remove an M S-D OS subdirectory 

mmove—M ove or renarne an M S-D OSfileor subdirectory 

mren— Renarne an existing M S-D OS fi le 

mtype— D isplay contents of an M S-D OS fi le 

mtest— Test and display the configuration 



mtest 



D ESC RIFIO N 

mtoois is a public domain collection of programsto allow U N IX systemsto read, write, and manipulate files on an MS-DOS 
fi lesystem (typically a floppy disk). W nere reasonable, each program attemptsto emulate the M S-DOS equivalent command. 
H owever, unnecessary restri ctions and odditiesof DOS arenot emulated. For instance, it ispossibleto movesubdirectories 
from one subdi rectory to another. 

M S-DOS fi lenames are opti onally composed of a drive letter followed by a colon, a subdirectory, and a filmarne. Filenames 
without a drive letter referto U N IX files. Subdirectory namescan useeither the / or \ separator. The use of the \ separator 
orwildcardswill requirethenamesto beenclosed in quotesto protectthem from theshell. (N ote Wildcardsin U N IX 
fi lenames should not beenclosed in quotes, becausehereuserswant theshell to expand them.) 

DIFFERENCES WITH MS-DOS 

Theregular expression "pattern matching" routinesfollow theU N IX-style rules. For example, * matchesall M S-DOS files 
in lieu of*.*. The archi ve, hidden, read-only, and system attri bute b i ts are i gn o red during pattern matching. 

Ali optionsusethe - (minus) flag, not / asyou'd expect in M S-DOS. 

M ost mtoois commands allow multi pie fi I enarri e parameters, which doesn't follow M S-DOS conventi ons, butwhich ismore 
user friendly. 

WORKING DIRECTORY 

Themcd command isused to establish the device and the current working directory (relative to the M S-DOS fi lesystem); 
otherwise, the default isassumed to beA:/. H owever, unii ke M S-DOS, thereisonly one working directory, and not one per 
drive. 

VFAT-STYLE LONG FILENAMES 

Thisversion of mtoois supportsVFAT-style long fi lenames. If a U N IX filename istoo longto fit in a short D OS name, it is 
stored asaVFAT long name, and a companion short nameisgenerated. Thisshort nameiswhatyou seewhen you examine 
the disk with a pre-7.0 version of DOS. The followingtable shows some examplesof short names: 

UNIX Name MS-DOSName Reason fortheChange 

thisisatest thisisat Filenametoo long 

alain.knaff ALAIN. KNA Extension tOO long 

prn.txt xrn.txt PRN isa device name 

.abc x.abc Nuli filename 

hot+coid hotxcold II legai character 

Theinitial U N IX-style fi lename(whether long or short) isalso called primary name, and thederived short name is al so called 
secondaryname 

Example: 

mcopy /etc/motd a:Reallylongname 

mtoois createsaVFAT entry for Reaiiyiongname, and uses reallylo as a short name Reaiiyiongname isthe primary name, and 
reallylo is the secondary name. 

In thisexample: 

copy /etc/motd a:motd 

motd fits into the DOS filename li mits mtoois doesn't need to derivate another name. motd isthe primary name, and thereis 
no secondary name. 

In a nutshdl: The primary name isthe long name, if oneexists, or the short nameif there isno long name. 
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NAME CLASHES 

When writing afileto disk, itslong name(primary name) or short namemay collide with an already existi ng fi le or 
directory. T hi s may happen for ali commands that create new directory entri es: mcopy, mmd, mren, mmove, mwrite, and mread. 

When anameclash happens, mtoois asksyou what itshould do. It offers several choices: 
overwrite 0 verwrites the existing file. It isnotpossibleto overwritea directory with afile. 
renarne Renamesthe newly created file mtoois will promptforthenew filename. 

autorename Renames the newly created file mtoois will chosea nameby itself, without prompting. 
skip Givesup on thisfile and moveson to the next (if any). 

To choosean option, typeits first letter at theprompt. If you use a lowercaseletter, theoption appliesforthisfileonly; if 
you usean uppercase letter, theoption appliesto ali files. 

You may also chooseoptions(forall files) on thecommand linewhen invoking mtoois: 

-o Overwritesprimary namesby default 

-o 0 verwrites secondary namesby default 

-r Renames primary nameby default 

-R Renamessecondary nameby default 

-a Autorenames primary name by default 

-a Autorenames secondary name by default 

-s Skips primary nameby default 

-s Skips secondary nameby default 

-m Asks user what to do with primary name 

-m Asks user what to do with secondary name 

By default, the user isprompted if the primary nameclashes, and the secondary nameisautorenamed. 
If a nameclash occursin aU N IX directory, mtoois only askswhetherto overwrite the fi le or to skip it. 

CASE SEN SITIVITY 0 F TH E VFAT FILESYSTEM 

TheVFAT filesystem isableto remem ber the case of thefilenames. However, filenamesthat differ only in casearenot 
allowed to coexist in the same directory. For exampleif you store a file called LongFiieName on a VFAT filesystem, mdir will 
show thisfile asLongFiieName, and notasLongfiiename. H owever, if you then try to add LongFiiename to the same directory, 
itwill berefused, because case isignored for clash checks. 

TheVFAT filesystem allowsthestoring of the case of a filename in the attribute byte, if ali lettersof the filename are the 
samecase, and if ali lettersof theextension are the same case too. mtoois usesthisinformation when displayingthefiles, and 
also to generate the U N IX when mcopying to aU N IX directory. This may haveunexpected resultswhen applied to files 
written usinga pre-7.0 versi on of DOS; indeed, thesefilenamesmap to ali uppercase. This isdifferent from thebehaviorof 
the old versi on of mtoois, which used to generate lowercase U N IX filenames. 

XDFDISKS (LINUX ONLY) 

Xdf isa high-capacity format supported byOS/2. Itcan hold 1,840KB per disc. That's not very high compared to thebest 
2m formats, but itsmain advantageisthat it is fast: 600 milliseconds per track. That's faster than thegood old 21 sector 
format, and al mostas fast as the standard 18 sector format. In order to access these di sks, settheuse_xdf vari able for the 
drive. Seemtoois(5) for detai Is on how to do this. Fast Xdf access is only available for kernel s more recent than 1.1.34. 



CAUTION 



Attention distri butors: If mtoois iscompiled on Linux, on a kernel more recent than 1.3.34, it won't run on an older 
kernel. H owever, if it has been compiled on an older kernel, itwill stili run on anewer kernel, except that Xdf access is 



mtype 




slower. It isrecommended that distri bution authorsonly include mtoois binarie compi led on kernelsolderthan 1.3.34 
until 2.0 comes out. W hen 2.0 isout, mtoois bi nari es compi led on newer kernelsmay (andshould) bedistributed. mtoois 
binariescompiled on kernelsolderthan 1.3.34 won't run on any kernel 2.1 or later. 

EXITCODES 

Ali the mtoois commands return a on success, 1 on utterfailure, or2 on partial failure. Ali themtoois commandsperform a 
few sani ty checksbeforegoing ahead, to makesure that the disk isindeed an M S-DOS disk (asopposed to, say, an ext2 or 
mi nix disk). Thesechecksmay reject partially corrupted disks, which mightotherwi se stili be readable. To avoid these 
checks, settheiKTooLs_sKip_cHECK environmental variable 

SEEALSO 

mattrib(l), mbadblocks(l), mcd(l), mdel(l), mformat(l), mmove(l), mrd(l), mren(l), mtype(l), mcopy(l), mdìr(l), mlabel(l), 
mmd(l), mmount(l) 

BUGS 

An unfortunatesideeffect of not guessingtheproper device (when multi pie disk capacitiesaresupported) isan occasionai 
error message from the device driver. T hese can be safely ignored. 

Thefat checking codechokeson 1.72M B disks mformatted with pre-2.0.7 mtoois. Set the environmental variable 
mtools_fat_compat i b i li ty to bypass thefat checking. 

Thesupportfor non-Linux OS vari antshas not been tested fora long ti me. It may contai n bugs, or even notwork at ali. 

Locai 

mtvtoppm 

mtvtoppm— Convert output from the MTV or PRT ray tracers into a portablepixmap 
SYNOPSIS 

mtvtoppm [ mt vf i I e ] 

DESCRIPTION 

mtvtoppm readsan input fi le from M ark Van DeWettering's MTV ray tracer and produces a portablepixmap as output. 
The PRT ray tracer also produces this format. 

SEEALSO 

ppm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

2 February 1989 

mtype 

mtype— D isplay contents of an M S-DOS file 
SYNOPSIS 

mtype [ -ts ] msdosfile [ msdosfiles... ] 
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mtype displays the specified M S-DOSfileon thescreen. 
mtype will allow thefollowing command-lineoptions: 

t Text fi le viewi ng. mtype will translate incoming carriage return/linefeeds to line feeds. 

s Strip high bit. mtype will stri p the high bitfrom the data. 

M S-D OS subdirectory namesaresupported with either the / or \ separator. The use of the \ separatororwildcardswill 
requirethenamesto beenclosed in quotesto protect them from the sfidi. 

Themcd command may beused to estabi ish the device and the current working directory (relative to M S-D OS); otherwise, 
the default ìsa:/. 

mtype returnso on success, 1 on utter fai Iure, or 2 on partial fai Iure. 
SEEALSO 

mcd(l), mread(l) 

BUGS 

Allows multiple arguments, which does not follow the MS-DOS convention. 

Locai 



mv 

mv— Renamefiles 
SYNOPSIS 

mv [options] source dest 

mv [options] source... directory 

Options: 

[-bfiuv] [-S backup-suff ix] [-V {numbered,existing,simple}] [--backup] [--force] 
[ - -interactive] [--update] [--verbose] [ - -suff ix=backup-suff ix] 
[ - -version-control={numbered, existing , simple} ] [ - -help] [ - -version] 

D ESC RIFIO N 

Thismanual page documents the GN U version of mv. If thelast argument namesan existing directory, mv moveseach other 
given fi le into a fi le with thesamenamein that directory. Otherwise, if onlytwo fi les aregi ven, itmovesthefirst onto the 
second. It isan errar if thelast argument is not a directory and morethan two fi les are given. It can moveonly regularfiles 
acrossfilesystems. If a destination fileisunwritable, the standard input isatty, and the-t or - -torce option is not given, mv 
prompts the user forwhetherto overwrite thefile. If the response does not begin with y ory, the fi le i s ski pped. 

OPTIONS 

-b, -backup M ake backupsof fi lesthat are about to be removed. 

-t, -torce Removeexistingdestination filesand never prompt the user. 

-i, - -interactive Prompt whether to overwrite each destination fi le that al ready exists. If the response does 

not beginwith yory, the fi le is ski pped. 
-u, - -update Do not move a nondirectory that hasan existing destination with thesameor newer 

modification time. 

-v, -verbose Print the nameof each file before moving it. 

-heip Printausagemessageon standard output and exit successfully. 

--version Print version information on standard output, then exit successfully. 
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-S, --suffix backup-suffix 



-V, - -version -control 
{numbered, existing.simple} 



The suffix used for maki ng si mple backup fi les can be set with the simple_backup_suffix 
environment variable, which can beoverridden by thisoption. If neither of thoseisgiven, 
the default is ", as it isin Emacs. 

Thetypeof backups madecan be set with the version_control environment variable, which 

can beoverridden by thisoption. If version_control isnot set and thisoption isnot given, 

thedefault backup typeisexisting. The valueof the version_control environment variable 

and theargumentto thisoption are liketheGN U Emacs version -control variable they 

al so recogn i ze syn o ny m s th at are m ore d escri pti ve. 

The vali d valuesarethefollowing (unique abbrevi ations are accepted): 

t or numbered--Alwaysmake numbered backups. 

mi or existing--M ake numbered backups of fi les that already havethem, si mple backups of 
theothers. 

never or simpie — Always make si mple backups. 

GNU Fi le U ti li ti es 



mwrite 

mwrite— Low-level write(copy) aUNIX fi le to MS-DOS 

SYNOPSIS 

mwrite [ -tnvmoOsSrRA ] uni xf il e msdosfile 

mwrite [ -tnvmoOsSrRA ] unixfile [ unixfiles ... ] msdosdi rectory 

D ESC RIFIO N 

Thiscommand is obsolete and only supplied for backward compatibility reasonswith old seri pts Usemcopy instead. 
SEEALSO 

mcopy(l), mtools(l) 



Locai 



namei 

namei— Follow a pattinarne unti I a terminal point isfound 
SYNOPSIS 

namei [-nix] pathname [ pattinarne ... ] 

D ESC RIFIO N 

namei uses its arguments as pathnamesto any typeof UN IX file (symlinks, fi les, directories, and so forth). namei then follows 
each pathname unti I a terminal point isfound (a fi le directory, char device, and so on). If itfindsa symbol ic link, the user 
shows the link, and startsfollowing it, indenti ng the output to show thecontext. 

Thisprogram isuseful forfinding too many ìeveis of symboiic links problems. 

For each lineoutput, namei outputsthefollowing charactersto identify the file types found: 

t : Thepathnametheuser iscurrently tryingto resolve 

d Directory 

1 Symboiic link (both thelink and its contents are output) 

s Socket 
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b Block device 

c Character device 

Regularfile 
? An errar of some kind 

Namei printsan informative messagewhen the maximum number of symbolic links this system can havehasbeen exceeded. 
OPTIONS 

-x Show mount point directorieswith aD rather than ad. 

-m Show the mode bitsof each file type in thestyleof is(l), forexample, rwxr-xr-x. 

AUTHOR 

Roger Southwick (rogers@amadeus.wr.tek.com) 

BUGS 

To bediscovered 

CAVEATS 

namei will follow an infinite loop of symbolic links forever. To escape, usesiGiNT (usually "c). 
SEEALSO 

ls(l), stat(l) 

Locai 

newaliases 

newaiiases— Rebuild the database for the mail aliases fi le 
SYNOPSIS 

newaliases 

DESCRIPTION 

newaliases rebuildsthe random access database for the mail aliases file. It must berun each timeit ischanged in orderforthe 
changeto takeeffect. 

SEEALSO 

aliases(5), sendmail(8) 

HISTORY 

The newaliases command appeared in BSD 4.0. 

BSD 4, 30 July 1991 

newgrp 

newgrp— Log in to a new group 
SYNOPSIS 

newgrp [ group ] 



ni 




D ESC RIFIO N 

newgrp changes the group i dentification of ite Caller, analogously to ìogin(l). Thesameperson remains logged in, and 
thecurrent directory isunchanged, but calculationsof access permissionsto filesareperformed with respectto thenew 
group ID . 

If no group isspecified, the G I D ischanged to thelogin GID . 
FILES 

/etc/group 
/etc/passwd 

SEEALSO 

login(l), group(5) 

Linux 0.99, 9 October 1993 



ni 

ni— N umber linesof files 
SYNOPSIS 

ni [-h header-style] [-b body-style] [-f footer-style] [-p] [-d ce] 
[-v start -number] [-i incrementi [-1 lines] [-s line-separator] 
[-w llne-no-width] [-n {ln,rn,rz}] [ - -header-numbering=style] 
[ - -body-numbering=style] [ ■ -footer-numbering=style] 
[ ■ -first-page=number] [ - -page-increment=number] [ - -no- renumber] 
[ - - join -blank -lines=number] [ - -number -separator=st ring] 
[ - - number -width=number] [ - - number -format={ In, rn, rz}] 
[ - -section-delimiter=cc] [--help] [--version] [file...] 



D ESC RIFIO N 

Thismanual page documento the GN U version of m. m copieseach given file, orthestandard input if none are given or 
when afilenamed - isgiven, to thestandard output, with linenumbersadded to someorall of thelines. 

m considers its input to becomposed of logicai pages; by default, the line number is reset to 1 at the top of each logicai page, 
m treatsall of the input files as a single document; it doesnot reset linenumbersor logicai pages between files. 

A logicai pageconsistsof threesections: header, body, and footer. Any of thesectionscan beempty. Each can benumbered 
in a different style from the others. 

Thebeginningsof the sectionsof logicai pages are indi cated in the input fi le by a linecontainingnothingexceptoneof the 
following deli miter strings: 

\ : \ : \ : start of header 
\ : \ : start of body 
\ : start of footer 

Thetwo charactersfrom which these strings are made can bechanged with an option (seethenext subsection), but the 
pattern and length of each string cannot bechanged. 

Thesection deli miter strings are replaced by an empty lineon output. Any textthat comes before the first section deli miter 
string in the input file isconsidered to be part of a body section, so a file that doesnot contai n any section del imi ter strings is 
considered to consist of a single body section. 



OPTIONS 

-h, - -header-numbering=style See - -f ooter-numbering. 
-b, - -body-numbering=style See - -footer-numbering. 
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-f, - -footer-numbering=style 



-p, - -no-renumber 
-v, - -first -page=number 
-i, - -page-increment=number 
-1, - - join-blank-lines=number 

-s, - -number-separator=string 

-w, - -number-width=number 

-n, - -number-f ormat={ln , rn , rz} 



-section -delimiter=cc 



-help 



Select the numbering stylefor lines in thefooter section of each logicai page. When a lineis 
not numbered, thecurrent linenumber isnot incremented, but the line number separator 
character is stili prepended to the line. T hestyles are 
a Number ali lines 

t N umber only nonempty lines (default for body) 

n N umber no li nes (default for header and footer) 

pregexp N umber only lines that contain a match for regexp 

Do not reset the line number at the start of a logicai page. 

Set the ini ti al linenumber on each logicai pagete number (default 1). 

Increment linenumbers by number (default 1). 

Consider number (default 1) consecutive empty linesto beone logicai line for numbering, 
and only number thelast one. W herefewer than number consecutive empty lines occur, do 
not number them. A n empty li ne is one that contai ns no characters, noteven spaces or tabs. 
Separate the li ne number from thetext I ine in the output with string (default isatab 
character). 

Use number characters for linenumbers (default 6). 

Select the line numbering format: 

in Left justifi ed, no leadingzeros 

rn Right justifi ed, no leading zeros (default) 

rz Right justified, leadingzeros 

Set thetwo delimiter characters that indicatethebeginningsof logicai pagesections: if only 
oneisgiven, thesecond remains :. To enter \, use \\. 
Print ausagemessageand exit with a nonzero status. 
Print version information on standard output, then exit. 

GNU TextUtilities 



nlmconv 

nimconv— C onvert object codeinto an N LM 
SYNOPSIS 

nlmconv[ -Ibf d na me j - -input-target=bf dname] [ -Ob f d n a me | 

- -output-target=bf dname ] [ -Th ea de r f il e j - -header-f ile=h e a d e r f il e ] 

[ -V|- -version ][--help ] infile outfile 

D ESC RIFIO N 

nimconv convertsthe relocatable object file infiie into theN etWareLoadableM odule(N LM ) outfiie, opti onally reading 
headerfiie for N LM header information. For instructionson writing the N LM command filelanguageused in header files, 
seeTheN etWareTool M aker Specificati on M anual, availablefrom N ovell, Inc. nimconv currently workswith i 386 object files 
in COFF, ELF, ora.out format, and with SPARC object files in ELF or a. out format, nimconv usestheGN U binary file 
descriptor library to read infiie. 

OPTIONS 

-i bf dname, C onsider the sourcefile's object format to bebfdname, ratherthan attemptingto deduceit. 

- -input-target=bf dname 

-o bf d n a me , W ri te the output fi le usi ng the object format bf dname. nimconv i nfers the output format 

--output-target=bf dname based on the i nput format, for example, for an i 386 input file the output format is 

nlm32-i386. 



nm 




-T headerf il e, 
- -header-f ile=h ea d e r f i I e 

-V, - -version 
-h, - -help 

SEEALSO 

binutiis entry in info; TheGN U BinaryU tilities, Roland H . Pesch (J une 1993). 
COPYING 

Copyright © 1993 F ree Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof this manual under the conditionsfor verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof this manual into another language, under the above condì ti ons 
for modifi ed versi ons, except that this permission notice may beincluded in translationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

Cygnusgupport, Junel993 



Reads headerf le for N LM header information. For instructionson writing theN LM 

command fi le language used in header files, seeT he NetWare Tool M aker Specificati on 

M anual, availablefrom N ovell, Inc. 

Show the version number of nimconv and exit. 

Show asummary of theoptionsto nimconv and exit. 



nm 



■List symbolsfrom object files 



SYNOPSIS 

nm [ -a| - -debug-syms] [-g] - -extern-only ][-B ] [-C ] - -demangle ] 

[-D | - -dynamic ] [-s ] - -print-armap] [-0 j - -print-f ile-name] 

[-n ! - -numeric-sort ] [-pj - -no-sort ] [-r ] - - reverse-sort ] [ - -size-sort ] 

[ -u ! - -undef ined-only] [ - -help ][--version ][-t r adi x ] - -radix=r a d i x ] 

[ -Pj-portability ] [ -f f or mat | - -format=f or mat ] [ - -target=bf d n a me ][ objfile ...] 

D ESC RIFIO N 

GN U nm lists the symbolsfrom object files obj f m e. If no object files are given asarguments, nm assumesa.out. 
OPTIONS 

The long and short formsof options, shown hereas alternati ves, areequivalent. 



-A, -0 

- -print-f ile-name 

-a, - -debug-syms 
-B 

-C, - -demangle 
-D, - -dynamic 

-f f 0 r ma t 

-g, - -extern-only 
-n, -v, - -numeric-sort 



Precede each symbol bythenameof theinput filewhere it wasfound, ratherthan 
identifyi ng the input fi le once only before ali of its symbols. 
D isplay debugger-only symbols; normally these are not listed. 
Thesameas --format=bsd (for compati bility with the M I PS nm). 
Decode (demangle) low-level symbol namesinto user-leve! names. Besides removi ngany 
initial underscoreprepended by thesystem, thismakesC-H-function names readable. 
D isplay the dynamic symbols ratherthan thenormal symbols This is only meaningful for 
dynamic objects, such ascertain typesof shared libraries. 

Use the output format for mat , which can bebsd, sysv, or posix. The default isbsd. Only the 
first character of format is significanti it can beeither uppercaseor lowercase. 
D isplay only external symbols. 

Sort symbols numeri cai ly by their addresses, not alphabetically by their names. 
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-p, - -no-sort 
-P, - -portability 

-s, - -print-armap 

-r, - - reverse-sort 
• -size-sort 

-t radi x , - -radix=r a d i x 

- -target=bf dname 

-u, - -undef ined-only 
-V, - -version 
- -help 

SEEALSO 

binutiis entry in info; TheGN U Binary Utilities, Roland H . Pesch (October 1991); ar(i), objdump(i), raniib(i). 

COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and di stri bute modi fi ed versi onsof this manual under the conditionsfor verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof this manual into another language under the above condì ti ons 
for modified versi ons, except that this permission notice may beincluded in translationsapproved by the Free Software 
Foundation instead of in theoriginal English. 

Cygnussupport, 5 N ovember 1991 

nntpget 

nntpget— Get U senet articlesfrom aremoteNNTP server 
SYNOPSIS 

nntpget [ -d dist ][-f file ][-n newsgroups ][-t timestring ][-o ][-u file ][-v ] host 

D ESC RIFIO N 

nntpget connectsto theN NTP server atthespecified host and retrieves articlesfrom it. The arti cles are sentto standard 
output. 

The-o flag may beused only if thecommand isexecuted on the host where the innd(8) server is running. If this fi ag isused, 
nntpget connectsto the specified remote host to retrievearticles. Any articlenot present in the locai hi story database isthen 
fetched from the remote site and offered to the locai server. 

If the -v flag isused with the-o flag, then theM essage-ID of each arti de wi II be sentto standard output asit isprocessed. 

The list of article M essage-ID sisnormally read from standard input. If the -f flag isused, then a newnews command isused 
to retri ève ali articlesnewerthan themodification dateof the specified fi i e. The -u flag i s the same except that if the transfer 
succeeded, thefilewill beupdated with a stati stics line modifying itstimestamp so that it can beused in later invocati ons. If 
the-t flag isused, then the specified ti me s t r i n g isused as the ti me and dateparameterto the newnews command. 



Don't bother to sort thesymbols in any order; just print them in theorder encountered. 
Use the PO SIX. 2 standard output format instead of the default format. Equivalentto -t 

posix. 

When listi ng symbolsfrom archivemembers, includetheindex, a mapping(stored in the 
archiveby ar or raniib) of which modulescontain definitionsforwhat names. 
Reverse the sense of the sort (whether numeric or alphabetic); let the last come first. 
Sort symbols by size. T he size is computed as the difference between the value of the symbol 
and the value of the symbol with thenext higher value T he size of the symbol isprinted, 
ratherthan the value. 

User adi x asthe radix for printing the symbol values. It must bed for decimai, o for octal, 
or x for hexadecimal. 

Specifyan object code format otherthan your system 's default format. Seeobjdump(l) for 
information on listing available formata 
Display only undefined symbols (thoseexternal to each object file). 
Show the version number of nm and exit. 
Show a summary of the opti ons to nm and exit. 



obj copy 




If either the-t or -f flagsareused, then the-n flag may beused to speci fy a newsgroup list and the-d flag may beused to 
specify a distri bution list. The default is* for ali newsgroups, and no distri bution list. 

BUGS 

Truncates articles at 512 lines. 
HI STORY 

Written by Ri eh $alz (rsaiz@uunet.uu.net) for InterNetN ews 
SEEALSO 

innd(8) 



obj copy 

objcopy— C opy and translate obj ect files 



SYNOPSIS 

objcopy [ -Fbf dname | - -target=bf dname ] 

[ -Ibf dname | - -input-target=bf dname ] [ -Ob f d ri a me | 

- -output-target=bf d na me ] [ -Rsecti onname | 

- -remove-section=s e c t i on na me ] [ -S| --strip-ali ][-g] 

--strip-debug ] [-x ] - -discard-all ][-X| 

- -discard-locals] [ — bb y t e | - - byte=b y t e ] [ — ±i nterl eave | 

- -interleave=i nt e r I ea ve ] [ -v ] - -verbose] [-V| 

--version ][--help ] infile [ outfile ] 

D ESC RIFIO N 

TheGNU objcopy utility copi es the contentsof an object fi le to another. objcopy usestheGNU BFD library to read and 
write the object files. It can write the desti nation object fi le in a format differentfrom thatof the source obj ect fi I e. Theexact 
behaviorof objcopy is controlied by command-lineoptions. 

objcopy createstemporary fi lesto do its translati ons and deletesthem afterward. objcopy usesBFD to do ali itstranslation 
work; it knowsabout ali theformatsBFD knowsabout, andthusisableto recognizemostformatswithout beingtold 
explicitly. 

infiie and outfiie are the source and output files, respectively. If you do not specify outfiie, objcopy createsa temporary file 
and destructively renamestheresultwith the nameof the input file. 

OPTIONS 

-i bfdname, C onsider the sourcefile's object format to be bf dname, ratherthan attemptingto deduceit. 

- -input-target=bf dname 

-o bfdname, W rite the output fi le usi ng the object format bf dna me . 

- -output-target=bf dname 

-f bfdname, Usebfdname astheobject format for both the input and the output file; that is, si mply 

--target=bf dname transfer datafrom source to desti nation with no translation. 

-R s ect i onname, Removethe named section from the fi le. Thisoption may begiven morethan once. N ote 

-- remove -section, =s ect i onname that using this option i nappropri ately may make the output fi le unusable. 

-s, -strip-aii Do not copy relocation and symbol information from the source fi le. 

-g, -strip-debug D o not copy debugging symbolsfrom the sourcefile. 

-x, --discard-aii D o not copy nonglobal symbols from the source file. 

-x, --discard-iocais Do not copy compiler-generated locai symbols. (T hese usuai ly start with l or .). 
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-b byte, - - byte=b y t e 



-i i nterl eave, 

- -interleave=i nterl ea «e 

-v, - -verbose 

-V, - -version 
- -help 



Keeponlyeverybyte byteof the input file (header data is not affected). byte can beinthe 
rangefrom 0 to the interieave-1. This option is useful for creati ng fi lesto program ROM s. 
It istypically used with an srec output target. 

Only copy oneout of every interieave bytes. Theoneto copy is sei ected by the-b or 

--byte option. The default is 4. T he interleave is ignored if neither -b nor - -byte isgiven. 

Verbose output: listali object fi les modified. In the case of archi ves, objcopy -v listsall 

members of the archi ve. 

Show the version number of objcopy and exit. 

Showasummaryoftheoptionsto objcopy and exit. 



SEEALSO 

binutiis entry in info; TheGN U B i nary U ti li ties, Roland H . Pesch (J une 1993). 
COPYING 

Copyright © 1993 F ree Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modified versi onsof this manual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof this manual into another language, under the above conditions 
for modified versi ons, except that this permission notice may beincluded in translationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

Cygnusgupport, Junel993 
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objdump— D i splay informati on from object files. 
SYNOPSIS 

objdump [ -a ] - -archive-headers ][-b\ bfdname | --target= bfdname ] 
[ -d | - -disassemble] [-D ] - -disassemble-all ] [-f j - -f ile-headers ] 
[ -b | - -section-headers ] --headers ] [ -i | - - info ][-j\ section 
| --section= section ] [-1] - -line-numbers ][-m\ machine ] -- 
-architecture= machine ][-r|--reloc ] [-R] - -dynamic-reloc ] 
[ -s| - -full-contents ][--stabs ] [ -t | - - syms ] [-T| - -dynamic- 
syms] [-x ! - -all-headers ][--version ][--help ] obj fi I e ... 

DESCRIPTION 

objdump displaysinformation about oneor more object files. The options control what parti cular information to display. This 
information ismostly useful to program merswho areworkingon the compilation tools, asopposed to programmerswho 
just wanttheir program to compi le and work. 

objfiie. . . are the object fi lesto beexamined. When you specify archi ves, objdump shows information on each of themember 
object files. 

OPTIONS 

W nere long and short formsof an option areshown together, they are equi valent. At leastone option besides-i (--une- 
numbers) must begiven. 

-a, - -archive-headers If any filesfrom obj fi i e are archi ves, display the archi ve header information (in a format 

similartois -1). Besidesthe information you could list with ar tv, objdump -a shows the 
obj ect fi le f o rm at of each arch i ve m em ber. 
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-b bf dna me , 

- -target=bf d n a me 



-d, - -disassemble 

-D, - -disassemble-all 

-f , - -f ile-headers 
-h, - -section-headers, 
- -headers 
- -help 
-i, - -info 

-j n a me , - -section=name 
-1, - -line-numbers 

-m ma c h ne, 

■ -architecture=mac h i ne 
-r, - -reloc 

-R, - -dynamic-reloc 

-s, - -full-contents 
- -stabs 



-t, - -syms 

-T, - -dynamic-syms 



- -version 

-x, - -all-headers 



Specify theobject-code format for the object fi lesto bebf dna me. Thismay not benecessary; 
objdump can automati cally recognizemanyformats. For example, objdump -b oasys -m vax - 
h fu.o displayssummary information from thesection headers (-h) of fu.o, which is 
explicitly i denti fied (-m) as a Vax object fi le in the format produced by Oasys compi lers You 
can list theformats availablewith the-i option. 

D i splay the assembler mnemonicsfor the machine instructions from obj f i i e. T hi s option 

only disassemblesthosesectionsthat areexpected to contain instructions. 

Like-d, but disassemble the contentsof ali sections, not just thoseexpected to contain 

instructions. 

D i splay summary information from theoverall header of each file in obj f m e. 
D i splay summary information from thesection headers of the object file. 

Printasummary of theoptionsto obj dump and exit. 

D i splay a list showi ng ali architecturesand object formatsavailablefor specification with -b 
or-m. 

D isplay information only for section name. 

Label the di splay (usi ng debugging information) with thefilenameand sourcelinenumbers 
correspondingto the object codeshown. Only useful with -d or -d. 
Specify the object files obj file are for archi tecture mac hi ne. You can list available architec- 
turesusingthe-i option. 

P ri nt the relocation entri esof the fi le. If used with -d or -d, the relocati ons are printed 
interspersed with thedisassembly. 

Print thedynamic relocation entri esof the fi le. Thisisonly meaningful for dynamicobjects, 

such ascertain types of shared libraries. 

D isplay the full contents of any sections requested. 

Di splay the contentsof the. stab, .stab. index, and .stab.exci sectionsfrom an ELF file. 
Thisisonly useful on systems (such as Solaris 2.0) in which .stab debugging symbol-table 
entri es are carri ed in an ELF section. In most otherfileformats, debugging symbol-table 
entri es are interleaved with linkage symbols, and are visi ble in the - -syms output. 
Symbol table. Print the symbol tabi e entri esof the file This issi mi larto the information 
provided by thenm program. 

Dynamic symbol table. Print thedynamic symbol table entri esof the fi le Thisisonly 
meaningful for dynamic objects, such ascertain types of shared libraries. Thisissimilar to 
the information provided by thenm program when given the -d (--dynamic) option. 
Print the version numberof obj dump and exit. 

Display ali available header information, includi ng the symbol tableand relocation entries. 
Using -x isequivalentto specifyingall of -a -f -h -r -t. 



SEEALSO 

binutiis entry in info; TheGN U Binary Utilities, Roland H . Pesch (October 1991); nm(i). 
COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission isgranted to makeand distribute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distribute modifi ed versi ons of this manual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati ons of this manual into another language, under the above conditions 
for modifi ed versi ons, except that this permission notice may beincluded in trans! ationsapproved by the Free Software 
Foundation instead of in theoriginal English. 

Cygnussupport, 5 N ovember 1991 
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oclock 

ociock— Round X clock 
SYNOPSIS 

oclock [-option ... ] 

D ESC RIFIO N 

ociock si mply displays the current ti me on an analog display. 
OPTIONS 

-fg color C hoose a different color for both hands and the jewel on the clock 

-bg color C hoose a different color for the background, 

-jewei color Choose a different color for thejewel ontheclock. 

-minute color C hoose a different color for the minute hand of the clock, 

-nour color C hoose a different color for the hour hand of theclock. 

-backing {wnenMapped Select an appropriate leve! of backingstore. 

Always NotUseful} 

-geometry geometry D efinethe initial window geometry; seex(l). 

-display display Specify the display to use; see x(l). 

-bd color Chooseadifferentcolorforthewindow border. 

-bw «i dth Choose a different width for the window border. As the C lock widget changes its border around 

quitea bit, this ismost usefully setto zero, 
-shape C ause the clock to usetheShapeextension to create an ovai window. This is the default unlessthe 

shapewindow resource is set to false, 
-nosnape Causetheclock to not reshapeitself and ancestorsto exactly fit the outl ine of theclock. 

-transparent C ause the clock to consist only of thejewel, the hands, and the border. 

COLORS 

If you would likeyour clock to beviewable in color, include thefollowing in the#ifdef color section you read with xrdb: 

"customization: -color 

Thiswill cause oclock to pick up thecolorsin the app-defaults color customization file: <xRoot>/iib/xn/app-defauits/ 
ciock-coior. Thedefault colorsare 

Clock*Background Gray 

Clock*BorderColor Light blue 

Clock*hour YellOW 

Clock*jewel YellOW 

Clock*minute YellOW 

SEEALSO 

x(l), X Toolkit documentation 

AUTHOR 

Keith Packard, M IT X Consortium 
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od 

od— D ump file in octal and other formats 
SYNOPSIS 

od [-abcdfhiloxv] [-s[bytes]] [-w[bytes]] [-A radix] [-j bytes] [-N bytes] 
[-t type] [ - -skip-bytes=bytes] [ ■ -address-radix=radix] [ - -read-bytes=bytes] 
[ - -format=type] [ - -output-duplicates] [ - -strings[=bytes] ] [ - -width[=bytes ] ] 
[ - -traditional] [--help] [--version] [file...] 



D ESC RIFIO N 

Thismanual page documents the GN U version of od. od writesto the standard output thecontentsof thegiven files, orof 
the standard input if thename- isgiven. Each li ne of the output consistsof the offset in the input file in the leftmost 
column of each line, followed by one or more columnsof data from thefile, in a format controlied by theoptions. By 
default, od pri nts the fi le offsets i n octal and the file data as two-byte octal numbers. 

OPTIONS 

-a, --address-radix=radi x Select the base i n which fi le offsets are printed. radix can beoneof thefollowing: 
d Decimai 
o 0 ctal 
x Hexadecimal 
n N one (do not pri nt offsets) 
Thedefault isoctal. 

-j, - -skip-bytes=byt es Skip bytes input bytes befo re formatti ng and writing. If bytes beginswith 0x or ax, it is 

interpreted in hexadecimal; otherwise, if it beginswith 0, in octal; otherwise, in decimai. 

Appendi ngb multi pi iesit by 512, k by 1024, and m by 1048576. 
-n, --read-bytes=bytes Only output up to byt es bytes of each input fi le. Any prefixes and suffixes on by t es are 

interpreted asforthe-j option. 
-t, - -formata ype Select the format in which to output the fi le data, t y p e isastringofoneormoreofthe 

followi ng type indicator characters If you include more than onetype indicator character in 

asingletype string or use this option more than once, od writes one copy of each output 

lineusing each of the data types that you specified, in theorder that you specified. 

a N amed character 

c ASC 1 1 character or backslash escape 

d Signed decimai 

f Floating point 

0 0 ctal 

u U nsigned decimai 
x Hexadecimal 

Except fortypesa and c, you can specify thenumber of bytes to use in interpreti ng each 
number in thegiven data type by followi ng the type indicator character with a decimai 
integer. Alternately, you can specify the sizeof one of the C compilerà built-in data types by 
followi ng the type indicator character with one of thefollowing characters. For integers (d, 
0, u, x): 
c char 
s short 

1 int 

l long 
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For floating point(f): 
f float 
d doublé 
l long doublé 

-v, -output-dupiicates Output consecutive linesthat are identical. By default, when two or more consecutive 

output lines would beequal, od outputsonly the first line, and putsjust an asterisk on the 
following lineto indicate that identical lines havebeen elided. 

-s, -strings[=bytes ] Instead of thenormal output, output only string constants in the input, which area run of 

atleastbytes ASCII graphic (or formatting) characters, terminated byaNUL. If bytes is 
omitted, it defaultsto 3. 

-w, --width[=bytes ] Thenumberof input bytes to format per output line. It must be a multiple of the least 

common multi pie of the sizes associ ated with the specified output types. If bytes is omitted, 
it defaultsto 32. Ifthisoption isnotgiven, it defaultsto 16. 

-heip Print ausagemessageand exit with a nonzero status. 

-version Print version information on standard output, then exit. 

Thenext several optionsmap the old, pre-POSIX format specification optionsto thecorresponding POSIX format specs. 
GNU od acceptsany combinati on of old- and new-styleoptions. Format specification options accumulate. 

-a 0 utput as named characters. Equivalent to -t a. 

-b 0 utput as octal bytes. Equivalent to -t oc. 

-c 0 utput as ASC 1 1 characters or backslash escapes. Equivalent to -t c. 

-d Output asunsigned decimai shorts. Equivalent to -t u2. 

-f Output as fi oats. Equivalentto -t fF. 

-h 0 utput ashexadeci mal shorts. Equivalentto -t x2. 

-i 0 utput as decimai shorts. Equivalentto -t d2. 

-1 0 utput as decimai longs. Equivalentto -t d4. 

-0 0 utput as octal shorts. Equivalent to-t 02. 

-x Output ashexadeci mal shorts. Equivalentto -t x2. 

-traditionai Recognize the pre-PO SIX nonoption argumentsthatsomeolderversionsof od accepted. 

Thefollowingsyntax: 

od --traditionai [file] [ [+]of f set [ . ] [b] [ [+] I a bel [ . ] [b] ] ] 
can beused to specify at most one file and optional arguments speci fyingan offset and a 
pseudo-start address, 1 abe . By default, offset isinterpreted asan octal number specifying 
how many input bytes to skip before formatting and writing. The optional trailing decimai 
poi nt forces the interpretati on of off set as a decimai number. If no decimai is specified and 
the offset beginswith u or ax, it isinterpreted asa hexadecimal number. If thereis a trailing 
b, thenumberof bytes skippedwill be of f s et multiplied by 512. The 1 abe argumentis 
interpreted just I i ke offset , but it specifiesan initial pseudo-address. Thepseudo addresses 
aredisplayed in parentheses following any normal address. 

GNU TextUtilities 



passwd 

passwd— C hange password 
SYNOPSIS 



passwd [ name ] 




D ESC RIFIO N 

passwd eh an ges th e speci f i ed user's password. 0 nly thesuperuser isallowed to changeother users' passwords. If the user is 
not root, thentheold password is prompted for and verified. 

A new password is prompted fortwice, to avoid typing mistakes. U nless the user is thesuperuser, thenew password must 
havemorethan six characters, and must haveeither both uppercaseand lowercaseletters, or nonletters. Some passwords that 
are similar to the user's name are not allowed. 

FILES 

/etc/passwd 
/etc/shells 

SEEALSO 

chsh(l), chfn(l) 

BUGS 

A password consisti ng of ali digits isallowed. 

N o warnings are printed if thesuperuser choosesa poor password. 

The-f and-s optionsarenotsupported. 

AUTHOR 

Peter Orbaek (poe9daimi.aau.dk) 

Linux 1.0, 22 Junel994 



paste 

paste— M erge lines of files 
SYNOPSIS 

paste [-s] [-d delìm-list] [--serial] [ - -delimiters=delim-list] [--help] 
[--version] [file...] 

DESCRIPTION 

Thismanual page documents the GN U version of paste, paste prints lines consisti ng of sequenti ally corresponding lines of 
each given file, separated by tabs, termi nated by a newline. If no files are given, the standard input isused. A filenameof - 
means standard input. 



OPTIONS 

-s, - -serial 

-d, --delimiters delim-list 
- -help 



Pastethe lines of onefi le at a time rather than onelinefrom each file. 
Consecutively use the characters in deiim-iist instead of tab to separate merged lines. 
When deiim-iist isexhausted, start again at its beginning. 
Print ausagemessageand exit with a nonzero status. 
Print version information on standard output, then exit. 

GNU TextUtilities 
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pbmclean 

pbmciean— Flip isolateci pixels in portable bitmap 
SYNOPSIS 

pbmclean [-connect] [pbmfile] 

DESCRIPTION 

pbmclean readsa portable bitmap as input and outputs a portable bitmap with every pixel that haslessthan connect identi cai 
neighborsinverted. pbmclean can beused to clean up "snow" on bitmap images. 

SEEALSO 

pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 

Permission to use, copy, modify, and distri butethis software and itsdocumentation for any purposeand without feeis 
hereby granted, provided that the above copyright noticeappear in ali copi es and that both that copyright noticeand this 
permission noticeappear in supporti ng documentation. This software is provided "as is" without express or implied 
warranty. 

pbmfilters 

pbmfiiters— List of ali programsin thePBM Plus package 



DESCRIPTION 




anytopnm 


Attemptto convertan unknown typeof imagefileto a portable anymap 


asciitopgm 


Convert ASCII graphics into a portable graymap 


atktopbm 


C onvert Andrew Toolkit raster object to a portable bitmap 


bioradtopgm 


Convert a Biorad confocal file into a portable graymap 


bmptoppm 


Convert a BM P file into a portable pixmap 


brushtopbm 


Convert a doodle brush file into a portable bitmap 


cmuwmtopbm 


Convert aCM U window manager bitmap into a portable bitmap 


fitstopnm 


Convert a FITS file into a portable anymap 


f stopgm 


C onvert a U senix FaceSaver file i nto a portable graymap 


g3topbm 


C onvert a G roup 3 fax file i nto a portable bitmap 


gemtopbm 


Convert a GEM IM G file into a portable bitmap 


gif topnm 


ConvertaGIF fileinto a portable anymap 


gouldtoppm 


Convert G ould scanner fi le into a portable pixmap 


hipstopgm 


Convert a H 1 PS file into a portable graymap 


hpcdtoppm 


Convert a Photo-C D fileinto a portable pixmap 


icontopbm 


Convert a Sun icon into a portable bitmap 


ilbmtoppm 


Convertan ILBM file into a portable pixmap 


imgtoppm 


Convert an IM G-whatnot fileinto a portable pixmap 


lispmtopgm 


Convert a Lisp machine bitmap fi le into PGM format 


macptopbm 


C onvert a M acPaint file into a portable bitmap 


mgrtopbm 


Convert an M GR bitmap into a portable bitmap 


mtvtoppm 


C onvert output from the MTV orPRT raytracers into a portable pixmap 



pbmfi Iters 



pbmclean 


Flip isolateci pixeìsin portable bitmap 


pbmlife 


Apply Conway'sRulesof Lifeto a portable bitmap 


pbmmake 


C reate a blank bitmap of a specified size 


pbmmask 


C reate a mask bitmap from a regular bitmap 


pbmpscale 


E nlarge a portable bitmap with edge smoothing 


pbmreduce 


Read a portable bitmap and reduce it N times 


pbmtext 


Render text into a bitmap 


pbmto10x 


Convert a portable bitmap into Gemini 10X printer graphics 


pbmto4425 


Display PBM imageson an AT&T 4425 terminal 


pbmtoascii 


Convert a portable bitmap into ASCII graphics 


pbmtoatk 


C onvert a portable bitmap to Andrew T oolkit raster object 


pbmtobg 


Convert a portable bitmap into BitGraph graphics 


pbmtocmuwm 


Convert a portable bitmap into aCM U window manager bitmap 


pbmtoepsi 


Convert a portable bitmap into an encapsulated PostScript 


pbmtoepson 


Convert a portable bitmap into Epson printer graphics 


pbmtog3 


C onvert a portable bitmap i nto a G roup 3 fax fi le 


pbmtogem 


Convert a portable bitmap into aGEM IM G file 


pbmtogo 


Convert a portable bitmap into compressed GraphOn graphics 


pbmtoicon 


C onvert a portable bitmap into a Sun icon 


pbmtolj 


Convert a portable bitmap into H P LaserJet format 


pbmtoln03 


Convert portable bitmap to D EC LN 03+Sixel output 


pbmtolps 


Convert portable bitmap to PostScript 


pbmtomacp 


Convert a portable bitmap into a M acPaintfile 


pbmtomgr 


C onvert a portable bitmap i nto an M G R bitmap 


pbmtopgm 


Convert a portable bitmap to portable graymap by averagingareas 


pbmtopi3 


Convert a portable bitmap into an Atari D egas . pi 3 file 


pbmtopk 


Convert a portable bitmap into a packed (PK) format font 


pbmtoplot 


C onvert a portable bitmap into a U N IX piot(5) file 


pbmtoptx 


Convert a portable bitmap into Printronix printer graphics 


pbmtox10bm 


Convert a portable bitmap into an X10 bitmap 


pbmtoxbm 


Convert a portable bitmap into an Xll bitmap 


pbmtozinc 


Convert a portable bitmap into a Z ine bitmap 


pbmupc 


C reate a U niversal Product C ode bitmap 


pcxtoppm 


Convert a PCX file into a portable pixmap 


pgmbentley 


Bentleyize a portable graymap 


pgmcrater 


C reate cratered terrai n by fractal forgery 


pgmedge 


Edge-detect a portable graymap 


pgmenhance 


Edge-enhance a portable graymap 


pgmhist 


Print a histogram of thevaluesin a portable graymap 


pgmkernel 


Generate a convoluti on kernel 


pgmnoise 


C reate a graymap madeup of white noise 


pgmnorm 


N ormalizethecontrast in a portable graymap 


pgmoil 


Turn a portable graymap into an oil painting 


pgmramp 


G enerate a grayscale ramp 


pgmtexture 


C alculate textural featureson a portable graymap 


pgmtofs 


C onvert a portable graymap to U senix FaceSaver format 
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pgmtolispm 


Convert a portablegraymap into Lisp machine format 


pgmtopbm 


Convert a portablegraymap into a portable bitmap 


pgmtoppm 


Colori ze a portablegraymap into a portable pi xmap 


pgmtoybm 


Convert a portable bitmap into a Bennet Yee"face" file 


piltoppm 


Convert an Atari DegasPll into a portable pixmap 


pi3topbm 


Convert an Atari Degas PI 3 file into a portable bitmap 


picttoppm 


Convert a M ad ntosh PICT file into a portable pixmap 


pjtoppm 


Convert an HP PaintJet file into a portable pixmap 


pktopbm 


Convert packed (PK) format font into portable bitmap(s) 


pnmalias 


Anti alias a portable anymap 


pnmarith 


Perform arithmetic on two portable anymaps 


pnmcat 


C oncatenate portable anymaps 


pnmcomp 


Composite two portable anymap files together 


pnmconvol 


General mxn convolution on a portable anymap 


pnmcrop 


Crop a portable anymap 


pnmcut 


C ut a rectangle out of a portable anymap 


pnmdepth 


Changethemaxvai in a portable anymap 


pnmenlarge 


Read a portable anymap and enlarge it N times 


pnmf ile 


D escri be a portable anymap 


pnmf lip 


Perform oneor moreflip operationson a portable anymap 


pnmgamma 


Perform gamma correction on a portable anymap 


pnmhistmap 


Draw ahistogram fora PGM or PPM file 


pnmindex 


Build a visual index of a bunch of anymaps 


pnminvert 


Invert a portable anymap 


pnmmargin 


Add a border to a portable anymap 


pnmnlf ilt 


N onlinear filters: smooth, alpha trim mean, optimal 


pnmnoraw 


Force a portable anymap into plain format 


pnmpad 


Add bordersto portable anymap 


pnmpaste 


Paste a rectangle into a portable anymap 


pnmrotate 


Rotate a portable anymap by some angle 


pnmscale 


Scalea portable anymap 


pnmshear 


Shear a portable anymap by some angle 


pnmsmooth 


Smooth out an image 


pnmtile 


Replicate a portable anymap into a specifi ed size 


pnmtoddif 


Convert a portable anymap to DDIF format 


pnmtofits 


Convert a portable anymap into F IT S format 


pnmtops 


C onvert portable anymap to PostScri pt 


pnmtorast 


Convert a portable pixmap into a Sun raster file 


pnmtosgi 


C onvert a portable anymap to an SG 1 i mage fi le 


pnmtosir 


Convert a portable anymap into a Solitai re format 


pnmtotiff 


Convert a portable anymap into aTIFF file 


pnmtoxwd 


Convert a portable anymap into an Xll window dump 


ppm3d 


Convert two portable pixmap into a red/blue3D glasses pixmap 


ppmbrighten 


Changean imagesSaturation andValuefrom an HSV map 


ppmchange 


Changeall pixelsof one color to another in a portable pixmap 


ppmdim 


Dima portable pixmap down to total blackness 
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ppmdist 


Simpli stic grayscaleassignment for machine generateci, color images 


ppmdither 


Ordered dither for color images 


ppmf lash 


Brighten a pictureup to complete white-out 


ppmforge 


Fractal forgeriesof clouds, planets, and starry skies 


ppmhist 


Print a histogram of a portable pixmap 


ppmmake 


C reate a pixmap of a speci fi ed size and color 


ppmmix 


Blend togethertwo portable pixmaps 


ppmnorm 


N ormalizethecontrast in a portable pixmap 


ppmntsc 


M ake a portable pixmap look likeit wastaken from an American TV show 


ppmpat 


M ake a pretty pixmap 


ppmquant 


Quantizethecolorsin a portable pixmap down to a speci fi ed number 


ppmquantall 


Run ppmquant on a bunch of filesall at once, so they share a common colormap 


ppmqvga 


8-plane quantization 


ppmrelief 


Run a Laplacian relief filter on a portable pixmap 


ppmshift 


Shift linesof a portable pixmap left or right by a random amount 


ppmspread 


D i splace a portable pixmap's pixels by a random amount 


ppmtoacad 


Convert portable pixmap to AutoCAD database or sii de 


ppmtobmp 


Convert a portable pixmap into a BM P file 


ppmtogif 


Convert a portable pixmap into a GIF file 


ppmtoicr 


Convert a portable pixmap into NCSA ICR format 


ppmtoilbm 


Convert a portable pixmap into an ILBM file 


ppmtomap 


Extractall col ors from a portable pixmap 


ppmtomitsu 


Convert a portable pixmap to a M itsubishi S340-10 file 


ppmtopcx 


Convert a portable pixmap into a PCX file 


ppmtopgm 


C onvert a portable pixmap i nto a portable graymap 


ppmtopil 


C onvert a portable pixmap i nto an Atari D egas P 1 1 fi le 


ppmtopict 


Convert a portable pixmap into a M acintosh PICT file 


ppmtopj 


Convert a portable pixmap to an H P PaintJet fi le 


ppmtopjxl 


Convert a portable pixmap into an H P PaintJet XL PC L file 


ppmtopuzz 


Convert a portable pixmap into an Xll "puzzle" file 


ppmtorgb3 


Separate a portable pixmap i nto three portable graymaps 


ppmtosixel 


Convert a portable pixmap into D EC sixel format 


ppmtotga 


Convert portable pixmap into a TrueVision Targa fi le 


ppmtouil 


Convert a portable pixmap into a M otif U IL icon file 


ppmtoxpm 


C onvert a portable pixmap i nto an X 11 pixmap 


ppmtoyuv 


Convert a portable pixmap into an AbekasYUV file 


ppmtoyuvsplit 


Convert a portable pixmap into three subsampled raw YUV files 


psidtopgm 


Convert PostScript "image" datainto a portable graymap 


pstopnm 


C onvert a PostScript file into a portableanymap 


qrttoppm 


C onvert output from the Q RT ray tracer into a portable pixmap 


rasttopnm 


C onvert a Sun raster fi le into a portable anymap 


rawtopgm 


C onvert raw grayscale bytes into a portable graymap 


rawtoppm 


Convert raw RGB bytes into a portable pixmap 


rgb3toppm 


C ombi ne three portable graymaps i nto one portable pixmap 


sgitopnm 


Convert an SGI image file into a portableanymap 


sirtopnm 


Convert a Sol itai re fi le into a portableanymap 
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sidtoppm Convert an AutoCAD slidefile into a portable pixmap 

spctoppm Convert an Atari compresseci Spectrum file into a portable pixmap 

spottopgm ConvertSPOT satell ite imagesto Portable Graymap format 

sputoppm Convert an Atari uncompressed Spectrum file into a portable pixmap 

tgatoppm C onvert T rueV ision Targa file into a portable pixmap 

tifftopnm ConvertaTIFF file into a portable anymap 

xbmtopbm Convert an Xll or X10 bitmap into a portable bitmap 

ximtoppm ConvertanXIM file into a portable pixmap 

xpmtoppm Convert an Xll pixmap into a portable pixmap 

xvminitoppm Convertan XV thumbnail pictureto PPM 

xwdtopnm Convert an Xll or X10 window dump fi le into a portable anymap 

ybmtopbm Convert a Bennet Yee"face" file into a portable bitmap 

yuvpiittoppm Convert a Y-, U- and V-fileinto a portable pixmap 

yuvtoppm Convert AbekasYUV bytes into a portable pixmap 

zeisstopnm C onvert a Zeiss confocal file into a portable anymap 

SEEALSO 

anytopnm(l), asciitopgm(l), atktopbm(l), bioradtopgm(l), bmptoppm(l), brushtopbm(l), cmuwmtopbm(l), f itstopnm(l), fstopgm(l), 
g3topbm(l), gemtopbm(l), giftopnm(l), gouldtoppm(l), hipstopgm(l), hpcdtoppm(l), icontopbm(l), ilbmtoppm(l), imgtoppm(l), 
lispmtopgm(l), macptopbm(l), mgrtopbm(l), mtvtoppm(l), pbmclean(l), pbmlife(l), pbmmake(l), pbmmask(l), pbmpscale(l), 
pbmreduce(l), pbmtext(l), pbmto10x(l), pbmto4425(l), pbmtoascii(l), pbmtoatk(l), pbmtobbnbg(l), pbmtocmuwm(l), pbmtoepsi(l), 
pbmtoepson(l), pbmtog3(l), pbmtogem(l), pbmtogo(l), pbmtoicon(l), pbmtolj(l), pbmtoln03(l), pbmtolps(l), pbmtomacp(l), 
pbmtomgr(l), pbmtopgm(l), pbmtopi3(l), pbmtopk(l), pbmtoplot(l), pbmtoptx(l), pbmtox10bm(l), pbmtoxbm(l), pbmtoybm(l), 
pbmtozinc(l), pbmupc(l), pcxtoppm(l), pgmbentley(l), pgmcrater(l), pgmedge(l), pgmenhance(l), pgmhist(l), pgmkernel(l), 
pgmnoise(l), pgmnorm(l), pgmoil(l), pgmramp(l), pgmtexture(l), pgmtofs(l), pgmtolispm(l), pgmtopbm(l), pgmtoppm(l), 
piltoppm(l), pi3topbm(l), picttoppm(l), pjtoppm(l), pktopbm(l), pnmalias(l), pnmarith(l), pnmcat(l), pnmcomp(l), pnmconvol(l), 
pnmcrop(l), pnmcut(l), pnmdepth(l), pnmenlarge(l), pnmfile(l), pnmflip(l), pnmgamma(l), pnmhistmap(l), pnmindex(l), 
pnminvert(l), pnmmargin(l), pnmnlf ilt(l), pnmnoraw(l), pnmpad(l), pnmpaste(l), pnmrotate(l), pnmscale(l), pnmshear(l), 
pnmsmooth(l), pnmtile(l), pnmtoddif (1), pnmtof its(l), pnmtops(l), pnmtorast(l), pnmtosgi(l), pnmtosir(l), pnmtotif f (1), 
pnmtoxwd(l), ppm3d(l), ppmbrighten(l), ppmchange(l), ppmdim(l), ppmdist(l), ppmdither(l), ppmflash(l), ppmf orge(l), 
ppmhist(l), ppmmake(l), ppmmix(l), ppmnorm(l), ppmntsc(l), ppmpat(l), ppmquant(l), ppmquantall(l), ppmqvga(l), ppmrelief (1), 
ppmshift(l), ppmspread(l), ppmtoacad(l), ppmtobmp(l), ppmtogif(l), ppmtoicr(l), ppmtoilbm(l), ppmtomap(l), ppmtomitsu(l), 
ppmtopcx(l), ppmtopgm(l), ppmtopil(l), ppmtopìct(l), ppmtopj(l), ppmtopjxl(l), ppmtopuzz(l), ppmtorgb3(l), ppmtosixel(l), 
ppmtotga(l), ppmtouil(l), ppmtoxpm(l), ppmtoyuv(l), ppmtoyuvsplit(l), psidtopgm(l), pstopnm(l), qrttoppm(l), rasttopnm(l), 
rawtopgm(l), rawtoppm(l), rgb3toppm(l), sgitopnm(l), sirtopnm(l), sldtoppm(l), spctoppm(l), spottopgm(l), sputoppm(1 ), 
tgatoppm(l), tif f topnm(l), xbmtopbm(l), ximtoppm(l), xpmtoppm(l), xvminitoppm(l), xwdtopnm(l), nybmtopbm(l), 
yuvsplittoppm(l), yuvtoppm(l), zeisstopnm(l) 

AUTHORS 

Many. See the individuai manual pages. 

pbmlife 

pbmiif e— Apply C onway's Rules of Life to a portable bitmap 
SYNOPSIS 

pbmlife [ p b mf i I e ] 



pbmmask 



D ESC RIFIO N 

pbmiife readsa portable bitmap as input, applies the Rules of Lifeto itforone generation, and producesa portable bitmap as 
output. 

A white pixel in theimageisinterpreted as a I i ve beasti e, and a black pixel asan empty space. 
SEEALSO 

pbm(5) 

AUTHOR 

C opyright © 1988, 1991 by J ef Poskanzer 

21 February 1991 

pbmmake 

pbmmake— C reate a blank bitmap of a speci fied size 
SYNOPSIS 

pbmmake [ -white | -black | -gray ] width h e i g h t 

D ESC RIFIO N 

pbmmake produces a portable bitmap of the specified width and height 
OPTIONS 

In addition to the usuai -white and -black, this program implements 
l's and O's alternati ng. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pbm(5), ppmmake(l) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer 

pbmmask 

pbmmask— C reate a mask bitmap from a regular bitmap 
SYNOPSIS 

pbmmask [ -expand] [pbmf il e ] 

D ESC Rimo N 

pbmmask reads a portable bitmap as input and createsacorresponding mask bitmap and writesit out. 

Thecolorto beinterpreted as background isdetermined automati cally. Regardlessof which color is background, themask 
will be white where the background is white and black wherethefigureis black. 



. The color defaultsto white. 

-gray. Thisgivesasimple50 percent gray pattern with 



22 February 1989 
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Thisletsyou do a masked paste likethis, for objects with a black background: 

pbmmask obj > objmask 

pnmpaste < dest -and objmask <x><y> ] pnmpaste -or obj <x><y> 

For objects with awhite background, you can either invert them or add a step: 

pbmmask obj > objmask 

pnminvert objmask ] pnmpaste -and obj 0 0 > blackback 

pnmpaste < dest -and objmask <x><y> ] pnmpaste -or blackback <x><y> 

N otethat thisthree-step versi on worksfor objects with black backgrounds, too, if you don't care about the wasted ti me. 
You can also usemaskswith graymapsand pixmaps, usingthepnmarith tool. For instance 

ppmtopgm obj.ppm | pgmtopbm -threshold | pbmmask > objmask. pbm 
pnmaritb -multiply dest.ppm objmask. pbm > tl.ppm 
pnminvert objmask. pbm ] pnmarith -multiply obj.ppm - > t2.ppm 
pnmaritb -add tl.ppm t2.ppm 

An interesting variati on on thisisto pipethemask through thepnmsmooth script beforeusing it. Thismakestheboundary 
between thetwo imageslesssharp. 

0PTl0^s 

-expand Expandsthe mask by one pixel outfrom theimage Thisisuseful if you want a little whiteborder around your 
image. (A better solution might beto turn thepbmiife tool into a general cellular automaton tool... ) 

SEE ALSO 

pnmpaste(l), pnminvert(l), pbm(5), pnmarith(l), pnmsmootb(l) 

AUTHOR 

C opyright © 1988 by J ef Poskanzer 

8 August 1989 

pbmpscale 

pbmpscaie— E nlarge a portable bitmap with edge smoothing 
SYNOPSIS 

pbmpscale N [ p b mf i I e ] 

DESCRIPTION 

pbmpscaie reads a portable bitmap as input and outputs a portable bitmap enlarged N times. Enlargement isdoneby pixel 
replication, with some additional smoothing of corners and edges. 

SEE ALSO 

pnmenlarge(l), ppmscale(l), pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 
NOTES 

pbmpscaie works best for enlargements of 2. Enlargementsgreaterthan 2 should bedoneby asmany enlargementsof 2 as 
possi ble, followed by an enlargement by the remaining faeton 



pbmtext 




pbmreduce 

pbmreduce— Read a portable bitmap and reduce it N times 
SYNOPSIS 

pbmreduce [ -f loyd | -f s | -threshold ][-valueval] N [ p b mf ile] 

D ESC RIPTIO N 

pbmreduce reads a portable bitmap as input, reduces it by afactor of n, and produces a portable bitmap as output. 

pbmreduce duplicatesa lot Of thefunctionality Of pgmtopbm; yOU COuId do SOmething like pnmscale | pgmtopbm, bUt pbmreduce 

isalotfaster. 

pbmreduce can beused to "re-halftone" an image. Say you have a scanner that only produces black and white, not grayscale, 
and it does a terrible job of halftoning (most black-and-white scanners fit this description). 0 ne way to fix the halftoning is 
to scan at the highest possible resolution, say 300dpi, and then reduce by afactor of threeor so usingpbmreduce.You can even 
correct the brightness of an image, by usingthe-vaiue flag. 

OPTIONS 

By default, the halftoning after the reduction isdonevia boustrophedonic Floyd-Steinberg errar diffusion; however, the - 
threshold flagcan beused to specify simplethresholding. Thisgives better resultswhen reducing line drawings. 

The -vaiue flag alters the thresholdingvalue forali quantizations. It should bea real number between 0 and 1. Above0.5 
meansdarker images; below 0.5 meanslighter. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pnmenlarge(l), pnmscale(l), pgmtopbm(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

2 August 1989 

pbmtext 

pbmtext— Render text into a bitmap 
SYNOPSIS 

pbmtext [-font f ont f i I e ] [-builtin font nanne ] [t ext ] 

DESCRIPTION 

pbmtext takes the specified text, either a single li ne from thecommand line or multiple linesfrom standard input, and renders 
it into a bitmap. 

OPTIONS 

By default, pbmtext usesa bui It-in font called bdf (about a 10-point Times Roman font). You can useafixed-width font by 

specifying -builtin fixed. 

You can also specify your own font with the -font flag. Thef ont f i i e is either a BDF fi le from theX Window System or a 
PBM file. 
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If the f ontf i i e isa PBM file, it iscreated in a very specific way. In your window system of choice, display the following text 
in the desi red (fixed-width) font: 

M ",/" [ ' j pq y | M 
/ !"#$%&'()*+ / 
< ,-./01 234567 < 
> 89: ;<=>?@ABC > 
0 DEFGHIJKLMNO 3 
PQRSTUVWXYZ[ 
{ \]" 'abcdefg { 
} hijklmnopqrs } 

tuvwxyz{ | }"" 
M " >/" [ ' ] pq y ! M 

Do ascreen grab or window dump of thattext, usingfor instancexwd, xgrabsc, or screen-dump. Converttheresult into a 
PBM file If necessary, usepnmcut to removeeverythingexcept the text. Finally, run itthrough pnmcrop to makesurethe 
edgesarerightup against the text. pbmtext can figure out the sizes and spaci ngsfrom that. 

SEEALSO 

pbm(5), pnmcut(l), pnmcrop(l) 

AUTHOR 

Copyright© 1993 byjef Poskanzer and George Phillips 

26 October 1993 

pbmto10x 

pbmtoi0x— ConvertaportablebitmapintoGemini 10X printer graphics 
SYNOPSIS 

pbmto10x [ -h] [ p b mf i I e ] 

D ESC RIPTIO N 

pbmtoiox readsa portable bitmap as input and producesafileof Gemini 10X printer graph icsas output. The lOX's printer 
codesarealleged to besimilarto theEpson codes. 

Note that thereis no lextopbm tool: thistransformation isone-way. 
OPTIONS 

The resolution isnormally 60H by 72V. If the -ti flag isspecified, resolution is 120H by 144V. You mayfind it useful to 
rotate landscape i mages before pri nting. 

SEEALSO 

pbm(5) 

AUTHOR 

Copyright© 1990 byKen Yapl 

January 1990 



pbmtoaazi i 

pbmto4425 

pbmto4425— D i splay PBM imageson an AT&T 4425 terminal 
SYNOPSIS 

pbmto4425 [ p b mf ile] 

D ESC RIPTIO N 

Pbmto4425 displaysPBM format imageson an AT&T 4425 ASCII terminal usingthatterminal'smosaic graphics character 
set. The program should also work with otherVT 100-1 ike termi nalswith mosaic graphics character setssuch astheC. I toh 
CIT-101, but it hasnotyet been tested on terminals other than the4425. 

Pbmto4425 puts the terminal into 132-column modeto achieve the maximum resolution of theterminal. In thismodethe 
terminal has a resolution of 264 columnsby 69 rows. The pixel shavean aspect ratio of 1:2.6; therefore, an image should be 
processed beforebeing displayed in a manner such asthis: 

% pnmscale -xscale 2.6 pnmfile \ 
| pnmscale -xysize 264 69 \ 
| ppmtopgm \ 
| pgmtopbm \ 
| pbmto4425 

AUTHOR 

C opyright © 1993 by Robert Perlberg 

pbmtoascii 

pbmtoascii— Convert a portable bitmap into ASCII graphics 
SYNOPSIS 

pbmtoascii [ -1x2| -2x4] [pbmf il e ] 

D ESC RIFIO N 

pbmtoascii reads a portable bitmap as input and producesa somewhat crude ASC II graphic as output. 
N otethat thereis no asciitopbm tool; thistransformation isone-way. 

0PTI0NS 

The -1x2 and -2x4 flagsprovidetwo alternate waysfor the bitsto get mapped to characters. W ith 1x2, the default, each 
character representsa group of 1 bit acrossby 2 bitsdown. With -2x4, each character represents2 bitsacrossby 4 bitsdown. 
With the 1x2 modeyou can see the individuai bits, so it'suseful for previ ewing small bitmapson a nongraphics terminal. 
The 2x4 modeletsyou display larger bitmapson a standard 80-column display, but it obscures bit-level details. 2x4 modeis 
also good for di splayinggraymaps. pnmscale -width iss | pgmnorm | pgmtopbm -thresh should gi ve good results. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1988, 1992 byjef Poskanzer 

20 M arch 1992 
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pbmtoatk 

pbmtoatk— Convert portable bitmap to Andrew Toolkit raster object 
SYNOPSIS 

pbmtoatk [ p b mf ile] 

D ESC RIFIO N 

pbmtoatk reads a portable bitmap as input and producesan Andrew Toolkit raster object as output. 
SEEALSO 

atktopbm(l), pbm(5) 

AUTHOR 

Copyright© 1991 by Bill Janssen 

26 September 1991 

pbmtobg 

pbmtobg— Convert a portable bitmap into BitGraph graphics 
SYNOPSIS 

pbmtobg [rasterop][x y ]< p b mf il e 

D ESC RIFIO N 

pbmtobg reads a portable bitmap as input and producesBBN BitGraph terminal display pixel data (D PD) sequenceas output. 

Therasterop can bespecified on thecommand line. If thisisomitted, 3 (replace) will beused. A posi ti on in (x,y) coordi- 
natescan also bespecified. If both aregiven, therasterop comes first. The portable bitmap isalwaystaken from the standard 
input. 

Notethatthereisno bgtopbmtool. 
SEEALSO 

pbm(5) 

AUTHOR 

Copyright © 1989 by M ike Parker 

16 May 1989 

pbmtocmuwm 

pbmtocmuwm— Convert a portable bitmap into aCM U window manager bitmap 
SYNOPSIS 

pbmtocmuwm [ p b mf ile] 

D ESC Rimo N 

pbmtocmuwm reads a portable bitmap as input and producesa CM U window manager bitmap as output. 



pbmtoepson 359 

SEEALSO 

cmuwmtopbm(l), pbm(5) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer 

15 Aprii 1989 



pbmtoepsi 

pbmtoepsi— Convert a portablebitmap into an encapsulated PostScript-style preview bitmap 
SYNOPSIS 

pbmtoepsi [ -bbonly] [pbmf i I e ] 

D ESC RIPTIO N 

pbmtoepsi reads a portable bitmap asinput and produce an encapsulated PostScript-style bitmap as output. The output is 
not a standalone PostScript file it isonly a previ ew bitmap, which can beincluded in an encapsulated PostScript file. N ote 
thatthereisno epsitopbm tool; thistransformation isone-way. 

This utility isa part of thepstoepsi tool by Doug Crabill (dgc@cs.purdue.edu). 
OPTIONS 

■bboniy 0 nly create a boundary box, don'tfill itwith theimage. 
SEEALSO 

pbm(5), pnmtops(l), psidtopgm(l) 

AUTHOR 

Copyright© 1988 byjef Poskanzer, modified by Doug Crabill 1992 

1992 



pbmtoepson 

pbmtoepson— Convert a portablebitmap into Epson printer graphics 
SYNOPSIS 

pbmtoepson [pbmf i I e ] 

D ESC RIFIO N 

pbmtoepson reads a portable bitmap as input and produces a file of Epson printer graphics as output. 
N otethat thereisno epsontopbm tool; thistransformation isone-way. 

SEEALSO 

pbm(5) 

AUTHOR 

Copyright© 1991 byjohn Tiller (tiiier@gaiois.msfc.nasa.gov) and Jef Poskanzer 

4 January 1991 



Parti: U ser Commands 



pbmtog3 

pbmtog3 — C onvert a portable bitmap into a G roup 3 fax file 
SYNOPSIS 

pbmtog3 [ p b mf ile] 

D ESC RIFIO N 

pbmtog3 reads a portable bitmap as output and producesaGroup 3 fax fi le as input. 
REFERENCES 

Thestandard for Group 3 fax isdefined in CCITT Recommendation T.4. 

BUGS 

Probably. 

SEEALSO 

g3topbm(l), pbm(5) 

AUTHOR 

Copyright© 1989 by Paul Haeberli (<paui(?manray.sgi.com>) 



2 October 1989 



pbmtogem 

pbmtogem— Converta portable bitmap into a GEM IMG file 
SYNOPSIS 

pbmtogem [ p b mf i I e ] 

D ESC RIFIO N 

pbmtogem reads a portable bitmap as input and producesa compressed GEM IMG file as output. 
BUGS 

pbmtogem does not support compression of repeated lines. 
SEEALSO 

gemtopbm(l), pbm(5) 

AUTHORS 

Copyright © 1988 by D avid Beckemeyer and Jef Poskanzer 

11 July 1992 

pbmtogo 

pbmtogo— C onvert a portable bitmap into compressed GraphOn graphics 
SYNOPSIS 

pbmtogo [ p b mf i I e ] 



pbmtolj 

D ESC RIFIO N 

pbmtogo reads a portable bitmap as input and produce 2D compressed GraphO n graphics as output. Besureto set up your 
GraphOn with the followi ng modes: 8 bits/no parity; obeys no XON/XOFF; NULsareaccepted. Theseareall on theComm 
menu. Also, remember to turn off tty post processing. N otethat thereisno gotopbm tool. 

SEEALSO 

pbm(5) 

AUTHORS 

Copyright© 1988, 1989 byjef Poskanzer, M ichael Haberler, and BoThide 

24 N ovember 1989 

pbmtoicon 

pbmtoicon— C onvert a portable bitmap into a Sun icon 
SYNOPSIS 

pbmtoicon [ p b mf ile] 

D ESC RIPTIO N 

pbmtoicon reads a portable bitmap as input and producesaSun icon as output. 
SEEALSO 

icontopbm(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

31 August 1988 

pbmtolj 

pbmtolj — C onvert a portable bitmap into H P LaserJet format 
SYNOPSIS 

pbmtolj [-resolution N ][ -float ][- no reset ][ p b mf i le] 

DESCRIPTION 

pbmtolj reads a portable bitmap as input and producesH P LaserJet data as output. 
N otethat there is no ìjtopbm tool. 

OPTIONS 

-resolution Specifiesthe resolution of the output device, in dpi. Typical valuesarezs, 100, 150, 300. The default is 75. 

-fioat Suppressespositioning information. Thedefault isto writethesequenceEsc & 1 0 e to the output fi le. 

-noreset Prevents pbmtolj from writing the reset sequencesto thebeginningand end of the output fi le. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pbm(5) 



Parti: U ser Commands 



AUTHORS 

Copyright© 1988 byjef Poskanzer and M ichael Haberler. -fioat and -noreset optionsadded by Wim Lewis 

29 Auguà 1988 

pbmtoln03 

pbmtoin03— Convert portable bitmap to D EC LN 03+Sixel output 
SYNOPSIS 

pbmtoln03 [ -rltbf ] p b mf i I e 

D ESC RIFIO N 

pbmtoin03 reads a portable bitmap as input and producesa D EC LN 03+Sixel output file. 



OPTIONS 






-1 nn 


Usenn 


asvaluefor left margin (default 0). 


-r nn 


Usenn 


asvaluefor right margin (default 2400). 


-t nn 


Usenn 


asvaluefortop margin (default 0). 


-b nn 


Usenn 


asvaluefor bottom margin (default 3400 


-f nn 


Usenn 


asvaluefor form length (default 3400). 


SEEALSO 






pbm(5) 






AUTHOR 







Tim Cook, 26 February 1992 

7 Mayl993 

pbmtolps 

pbmtoips— C onvert a portable bitmap to PostScript 
SYNOPSIS 

pbmtolps [ -dpi n ] [ p b mf i I e ] 

DESCRIPTION 

pbmtoips reads a portable bitmap as input, and outputs PostScript. The output PostScript uses lines instead of theimage 
operatorto generate a (device-dependent) pi cture that wi II beimaged much faster. 

The PostScript path length isconstrained to belessthat 1000 pointsso that no limitsareoverrun on the Apple Laserwriter 
and (presumably) no other printers. 

SEEALSO 

pgmtops(l), ppmtops(l), pbm(5) 

AUTHOR 

George Phillips (<phiiiips§cs.ubc.ca>) 



pbmtomgr 



pbmtomacp 

pbmtomacp— Convert a portable bitmap into a M acPaint file 
SYNOPSIS 

pbmtomacp [-1 I ef t ] [ -r r i gltt ] [ -b b o 1 1 o m ] [ - 1 top ] [ p b mf ile] 

D ESC RIPTIO N 

pbmtomacp reads a portable bitmap as input. If no input file isgiven, standard input isassumed. Produces a M acPaint fileas 
output. 

Thegenerated fileisonly the data fork of a picture. You wi II need a program such asmcvert to generate a M acbinary or a 
BinH ex file that contai ns the necessary information to identify the fileas a PNTG fileto M acOS. 

OPTIONS 

Left, ri ght , bottom, and top I et you defi ne a square i nto thePBM file, which must beconverted. D efault isthewholefile. If 
thefileistoo largefor a M acPaint file, the bitmap iscut to fit from (i ef t , top). 

BUGS 

T he source code contai nscomments in a languageother than English. 
SEEALSO 

ppmtopict(l), macptopbm(l), pbm(5), mcvert(l) 

AUTHOR 

Copyright © 1988 by D ouwevan der Schaaf (. . . imcvaxiuvapsyivdschaaf) 

31 Auguà 1988 

pbmtomgr 

pbmtomgr— Convert a portable bitmap into an MGR bitmap 
SYNOPSIS 

pbmtomgr [ p b mf ile] 

DESCRIPTION 

pbmtomgr reads a portable bitmap as input and produces an MGR bitmap as output. 
SEEALSO 

mgrtopbm(l), pbm(5) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer 

24 January 1989 
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pbmtopgm 

pbmtopgm— C onvert portable bitmap to portable graymap by averaging areas 
SYNOPSIS 

pbmtopgm <width><height> [ p b mf ile] 

D ESC RIFIO N 

pbmtopgm reads a portable bitmap as input and outputs a portable graymap created by averaging the num ber of pixelswithin a 
samplearea of width by height around each point. pbmtopgm issimilar to a special caseof ppmconvoi. A ppmsmooth step may be 
needed after pbmtopgm. 

pbmtopgm has the effect of antiali asi ng bi tmaps that contai n di sci net line features. 
SEEALSO 

pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 
NOTES 

pbmtopgm works bestwith odd samplewidthsand heights. 

pbmtopi3 

pbmtopi3— C onvert a portable bitmap i nto an Atari D egas P 1 3 fi le 
SYNOPSIS 

pbmtopi3 [pbmfile] 

D ESC RIFIO N 

pbmtopi3 reads a portable bitmap asinput and producesan Atari D egas PI 3 fi le as output. 
SEEALSO 

pi3topbm(l), pbm(5), ppmtopil(l), piltoppm(l) 

AUTHOR 

Copyright© 1988 by David Beckemeyer (bdtidavid) and J ef Poskanzer. 

11 March 1990 

pbmtopk 

pbmtopk— C onvert a portable bitmap into a packed (PK) format font 
SYNOPSIS 

pbmtopk pkfile[.pk] tfmf ile[ .tfm] resolution [-s designsize] [-p num param...] 
[-C cod-ingscheme] [-F family] [-f optfile] [-0 num] [ -W width] [-H height] 
[-D depth] [-1 ital] [-hhoriz] [-vvert] [-x xoff] [-y yoff] [pbmfile]... 



pbmtoplot 



365 



D ESC RIFIO N 

pbmtopk reads portablebitmapsas input and produces a packed (PK) font file and aTFM (TeX font metric) file as output. 
The resolution parameter indicates the resolution of the font, in dots per inch. If the filmarne - isused for any of the 
filenames, the standard input stream (or standard output, where appropriate) will beused. 

OPTIONS 

-s desi gnsi ze Sets the design size of the font, in TeX 's poi nts (72.27 pointsto the inch). The default design sizeisi. The 

TFM parametersaregiven as multiples of the design size. 
-p num param... Sets the first num font parameters for the font. T he fi rst seven parametersaretheslant, interword spaci ng, 

interword space stretchability, interword space shrinkability, x-height, quad width, and post-sentence extra 

space of the font. M ath and symbol fonts may have more parameters; seeTheTeXbookfor a list of these. 

Reasonable default values are chosen for parameters that are not speci fied. 
-c codi ngscheme Sets the codi ng scheme comment in theTFM file. 
-Ffamiiy Sets the font family comment in theTFM file, 

-f optf il e Reads thefi le o p t f i e, which should contai n a line of the form: 

fi lena me x of f yoff fiori z vert width height depth ita 

ThePBM filesspecified by thefilename parameters are i nserted consecutive^ in thefontwith the 
specified attributes. If any of the attri butes are om itted, or replaced with *, a default value will be 
calculated from the size of the bitmap. The setti ngsof the -w, -h, -d, -i, -ti, -v, -x, and -y optionsdo not 
affectcharacterscreated in thisway. Thecharacter number can bechanged by includinga I ine starting 
with =, followed bythenew number. Lines beginning with % or # are ignored. 

-c num Sets thecharacter number of the next bitmap encountered to no m. 

-w width SetstheTFM width of the next character to w dth (in design size multiples). 

-h height SetstheTFM height of the next character to hei ght (in design size multiples). 

-D depth SetstheTFM depth of the next character to dept h (in design size multiples). 

-i tal Sets the itali c correction of thenext characterto i tal (in design size multiples). 

■ h horiz Setsthehorizontal escapement of thenext character to hori z (in pixels). 

-v vert Sets the verti cai escapement of the next characterto «e rt (in pixels). 

-x xoff Setsthehorizontal offset of the next character to x off (in pixels). 

-y yoff Sets th e vertical offset of the next characterto yoff (in pixels, from thetop row). 

SEEALSO 

pktopbm(l), pbm(5) 

AUTHOR 

Adapted from T om Rokicki 's pxtopk by Angus D uggan (aj cdedcs .ed.ac.uk). 

6 August 1990 



pbmtoplot 

pbmtoplot— Con vert a portable bitmap into aUN IX piot(5) file 
SYNOPSIS 

pbmtoplot [pbmf I I e ] 

DESCRIPTION 

pbmtoplot reads a portable bitmap as input and producesaUN IX plot file. 
N otethat thereisno piottopbm tool; this transformati on isoneway. 
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SEEALSO 

pbm(5), plot(5) 

AUTHOR 

Copyright© 1990 by Arthur D avid 0 Ison. 

1 September 1990 

pbmtoptx 

pbmtoptx— Convert a portablebitmap into Printronix printer graphics 
SYNOPSIS 

pbmtoptx [ p b mf i I e ] 

DESCRIPTION 

pbmtoptx reads a portable bitmap as input and produce a file of Printronix printer graphics as output. 
N otethat thereisno ptxtopbm tool; thistransformation isone-way. 

SEEALSO 

pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

31 Auguà 1988 

pbmtox10bm 

pbmtoxiabm— Convert a portablebitmap into an X10 bitmap 
SYNOPSIS 

pbmtoxiabm [ p b mf i I e ] 

DESCRIPTION 

pbmtoxiabm reads a portable bitmap as input and producesan X10 bitmap as output. T hi solder format ismaintained for 
compati bility. 

N otethat thereis no xiabmtopbm tool because xbmtopbm can read both Xll and X 10 bitmaps. 
SEEALSO 

pbmtoxbm(l), xbmtopbm(l), pbm(5) 

AUTHOR 

Copyright® 1988 byjef Poskanzer. 

31 August 1988 



pbmtozi ne 

pbmtoxbm 

pbmtoxbm— Convert a portable bitmap into an Xll bitmap 
SYNOPSIS 

pbmtoxbm [ p b mf ile] 

D ESC RIFIO N 

pbmtoxbm reads a portable bitmap as input and produce an Xll bitmap as output. 
SEEALSO 

pbmtox10bm(l), xbmtopbm(l), pbm(5) 

AUTHOR 

C opyright © 1988 by J ef Poskanzer. 

31 Auguà 1988 

pgmtoybm 

pgmtoybm— Convert a portable bitmap into a Bennet Yee"face" file 
SYNOPSIS 

pbmtoybm [ p b mf i I e ] 

D ESC RIFIO N 

pgmtoybm reads a portable bitmap as input and produces as output a file acceptableto theface and xbm programsby Bennet 

Yee(bsy+@cs. cmu.edu). 

SEEALSO 

ybmtopbm(l), pbm(5), face(l), face(5), xbm(l) 

AUTHORS 

Copyright© 1991 byJamieZawinski and Jef Poskanzer. 

6 M arch 1990 

pbmtozinc 

pbmtozinc— Convert a portable bitmap into aZinc bitmap 
SYNOPSIS 

pbmtozinc [ p b mf il e ] 

D ESC RIFIO N 

pbmtozinc reads a portable bitmap as input and produces a bitmap in the format used by the Zi ne Interface Library (ZIL) 
versi on 1.0 as output. 

SEEALSO 

pbm(5) 
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AUTHORS 

Copyright © 1988 by J ames D arrell M cCauley (jdm5548@diamond.tamu.edu) andjef Poskanzer. 



2 N ovember 1990 



pbmupc 

pbmupc— C reate a U niversal Product C ode bitmap 
SYNOPSIS 

pbmupc [-si J -s 2 ] type ma n u f a c product 

D ESC RIFIO N 

pbmupc generatela U niversal Product Code symbol. Thethreearguments are: a one-digit product type, a five-digit manufac- 
turer code, and a five-digit product code. Forexample, 0 72890 00011 isthecodefor H eineken. 

Aspresently configured, pbmupc produces a bitmap 230 bitswideand 175 bits high.Thesizecan bealtered by changingthe 
defines at the beginning of the program, or by running the output through pnmeniarge or pnmscaie. 

OPTIONS 

The-si and -s2 flagsselectthestyleof UPC to generate. The default, -si, looksmoreor lesslikethis: 



0| 1 1 2345 | ì 67890 | | 5 

Theother style, -s2, puts the product type digit higher up, and doesn't display the cnecksum digit: 



| | 12345| | 67890| 

SEEALSO 

pbm(5) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer. 

14 M arch 1989 



pcxtoppm 

pcxtoppm— Convert a PCX fileinto a portablepixmap 
SYNOPSIS 

pcxtoppm[pcxf Me] 

D ESC RIFIO N 

pcxtoppm readsaPCX fileasinput and produces a portablepixmap as output. 



pgmbentley 
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SEEALSO 

ppmtopcx(l), ppm(5) 

AUTHOR 

C opyright © 1990 by M ichael D avidson. 

9 Aprii 1990 



pfbtops 

pfbtops— Translate a PostScript font in PFB formatto ASCII 



SYNOPSIS 

pfbtops [ p f b _ f i le ] 

DESCRIPTION 

pfbtops translates a PostScript font in PFB formatto ASCII. If pfb_me isomitted, thePFB filewill beread from the 
standard input. T he ASC 1 1 format PostScript font will bewritten on thestandard output. PostScript fontsforM S-DOS are 
normally supplied in PFB format. 

T he resulti ng ASCII format PostScript font can beused with groff. It must first belisted in /usr/iib/groff/font/devps/ 

download. 

SEEALSO 

grops(l) 

Groff Version 1.09, 6 August 1992 



pgmbentley 

pgmbentley— Bentleyize a portable graymap 
SYNOPSIS 

pgmbentley [pgmfile] 

DESCRIPTION 

pgmbentley reads a portable graymap asinput, performstheBentleyEffect, and writes a portable graymap as output. 

TheBentley Effect isdescribed in Beyond Photography by H olzmann, Chapter 4, photo 4. It'sa vertical smearing based on 
bri ghtness. 

SEEALSO 

pgmoil(l), ppmrelief (1), pgm(5) 

AUTHOR 

Copyright © 1990 by W ilson Bent (whb@hoh-2.att.com). 

11 January 1991 
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pgmcrater 

pgmcrater— C reate cratered terrai n by fractal forgery 
SYNOPSIS 

pgmcrater [-number n ] [ -height | -ysize s ] [ -width ] -xsize s] [-gamma g] 

D ESC RIFIO N 

pgmcrater create a portable graymap that mim ics cratered terrai n. The graymap iscreated by simulating the impact of a 
given number of craters with random position and size, then rendering the resulting terrain elevati onsbased on a light source 
shining from onesideof the screen. The size distri bution of the craters isbased on a power law that resultsin many more 
striali craters than largeones. The number of craters of a given size variesas the reciprocai of the area asdescribed on pages31 
and 32 of The Sd enee Of Fractal Images, edited by H .0. Peitgen and D . Saupe(N ew York: Springer-Verlag, 1988). Cratered 
bodies in the solar system areobserved to obey this relati onship. The formula used to obtain crater radii governed by this law 
from a uniformly distri buted pseudorandom sequencewasdeveloped by Rudy Rucker. 

H igh resolution images with largenumbers of craters often benefit from being piped through pnmsmooth.Theaveraging 
performed by thisprocesseliminatessomeof thejagged pixelsand lendsamellow "telescopic image" feel to theoverall 
picture. 

OPTIONS 

-number n Causesn cratersto begenerated. If no -number specification is given, 50,000 craters will begenerated. Don't 
expect to seethem ali! For every large crater, there are many, many more ti ny ones that tend simplyto erode the landscape. 
In general, the more craters you speci fy, the more realisti c the result; ideally, you want the enti re terrai n to havebeen 
extensively turned over again and again by crateri ng. H igh-resolution i mages contai ni ng fi veto ten mi II ion craters are 
stunni ng but take quite a while to create. 

-height height Sets the height of the generated image to he i g ht pixels. The default height is 256 pixels. 

-width width Sets the width of the generateci imageto wi dth pixels. The default width i s 256 pixels. 

-xsize width Setsthewidth of the generated imagetowi dth pixels. The default width i s 256 pixels. 

-ysize height Sets the height of the generated image to he i g ht pixels. The default height is 256 pixels 

-gamma f actor T he specified tactor isused to gamma correct the graymap in thesamemanner as performed by pnmgamma. 

The default value is 1 .0, which resultsin a medium co ntrast image. Values larger than 1 lighten the image 
and reduce contrast, while values lessthan 1 darken the image, increasing contrast. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
BUGS 

The -gamma option isn't really necessary becauseyou can achievethesameeffect by pi pi ng the output from pgmcrater 
through pnmgamma. H owever, pgmcrater performsan internai gamma map anyway in theprocessof rendering theelevation 
array into a graymap, so there'sno additional overhead in allowingauser-specified gamma. 

Real craters havetwo distinct morphologies. pgmcrater simulates only small craters, which are hemispherical in shape 
(regardlessof the incidence angle of the impacting body, aslong asthe velocity is sufficiente high). Large craters, such as 
CopernicusandTycho on themoon, havea"walled piai n" shape with across-section morelike: 

/\/\ 

/ \ /\ / \ 

Larger craters should really use this profile, including the centrai peak, and total ly obliterate the preexi sti ng terrai n. 
SEEALSO 



pgm(5), pnmgamma(l), pnmsmooth(l) 



pgmenhance 



AUTHOR 

John Walker 

Autodesk SA Avenue des C hamps-M ontants 14b 
CH-2074MARIN 

Sui sse/ Sch wei z/ Svi zzerà/ Svizra/ Swi tzerl an d 

Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 
Voice 038/33 76 33 

Permission to use, copy, modify, and distri butethis software and its documentati on for any purposeand without feeis 
hereby granted, without any conditionsor restri ctions. T hi s software isprovided "asis" without express or implied warranty. 

PLUGWARE! If you likethiskind of stuff, you may also enjoyJamesGleick's"Chaos— TheSoftware" for M S-DOS, 
available for $59.95 from your locai software store or di rectly from Autodesk, Inc., Attn: Science Seri es, 2320 M arinship 
Way, Sausalito, CA 94965, USA. Telephone: 800-688-2344 toll-free or, outsidetheU .5. (415) 332-2344 Ext 4886. Fax: 
415-289-4718. "C haos— TheSoftware" includesamorecomprehensivefractal forgery generatorthatcreatesthree- 
dimensional landscapesaswell ascloudsand planets, plus five more modulesthatexploreotheraspectsofC haos. The user 
guideof morethan 200 pagesincludesan introduction byJamesGleick and detailed explanationsby Rudy Rucker of the 
mathematicsand algorithmsused by each program. 

15 October 1991 

pgmedge 

pgmedge— Edge detect a portable graymap 
SYN0PSIS 

pgmedge [pgmfile] 

D ESC RIPTI0 N 

pgmedge reads a portable graymap as input, outlinestheedges, and writes a portable graymap as output. Pi pi ng the result 
through pgmtopbm -threshold and playing with thethreshold valuewill givea bitmap of theedges. 

The edge detection techniqueused isto takethePythagorean sum of two Sobel gradient operatorsat90 degreesto each 
other. For more details see D igital I mage Processing by Gonzalez and W intz, C hapter 7. 

SEE ALSO 

pgmenhance(l), pgmtopbm(l), pgm(5), pbm(5) 

AUTHOR 

Copyright © 1991 byjef Poskanzer. 

4 February 1990 

pgmenhance 

pgmenhance— Edgeenhancea portable graymap 
SYN0PSIS 

pgmenhance [ -N ] [pgmf il e ] 
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D ESC RIFIO N 

pgmenhance reads a portable graymap asinput, enhancestheedges, and writes a portablegraymap as output. 

Theedgeenhancingtechniqueistaken from Philip R. Thompson'sxim program, which took itfrom section 6 of Digital 
H alftonesbyDot Diffusion, D . E. Knuth, ACM Transaction on GraphicsVol. 6, N o. 4, October 1987, which in turn got it 
from two 1976 papersbyj. F. Jarviset. al. 

OPTIONS 

The optional -n flag should bea digit from 1 to 9. 1 isthe lowest level of enhancement, 9 isthe highest; the default is9. 
SEEALSO 

pgmedge(l), pgm(5), ppm(5) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer. 

13 January 1989 

pgmhist 

pgmhist— Print a histogram of thevaluesin a portablegraymap 
SYNOPSIS 

pgmhist [ p g mf il e ] 

DESCRIPTION 

pgmhist reads a portable graymap as input and prints a histogram of thegray values. 
SEEALSO 

pgmnorm(l), pgm(5), ppmhist(l) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer 

28 February 1989 

pgmkernel 

pgmkemei— Generate a convolution kernel 
SYNOPSIS 

pgmkernel [ -weight w ] width [ height ] 

DESCRIPTION 

pgmkemei generates a portablegraymap array of sizewi dt h x height (or width x width ifheight isnotspecified) to beused as 
a convolution fileby pnmconvoi. The data in the convolution array K arecomputed accordi ngto the formula: 



pgmnorm 

wherew is a coefficient specified via the -weight flag, and wi dt h andheight aretheX andY fi Iter sizes. 
The output PGM file isalwayswritten out in ASCII format. 

OPTIONS 

Theoptional -weight flag should be a real numPergreaterthan -1. The default value ÌS6.0. 
BUGS 

The computation timeis proporti onal to width * height. This increases rapidly with the increaseof the kernel size. A batter 
approach could Peto usea FFT in thesecases. 

SEEALSO 

pnmconvol(l), pnmsmooth(l) 

AUTHOR 

AlPertO Accomazzi (albertoUcfa.harvard.edu) 

10 Decemberl992 

pgmnoise 

pgmnoise— C reate a graymap made up of white noise 
SYNOPSIS 

pgmnoise width height 

DESCRIPTION 

pgmnoise creates a portaPle graymap that ismadeup of random pixel s with gray valuesin therangeof 0 to pgmjiaxmaxval 
(dependson the compilation, either 255 or 65535). The graymap has a size of width * height pixels. 

SEEALSO 

pgm(5) 

AUTHOR 

Copyright © 1993 by Frank N eumann 

16 N ovember 1993 

pgmnorm 

pgmnorm— N ormalizethecontrast in a portaPle graymap 
SYNOPSIS 

pgmnorm[ -bpercent N ] -bvalue N][-wpercent N ] -wvalue N] [pgmf i I e ] 

DESCRIPTION 

pgmnorm reads a portaPle graymap as input; normalizes the contrai Py forcing the lightest pixels to white, thedarkest pixels to 
black, and li nearly rescaling the ones in between; and produces a portaPle graymap as output. 

OPTIONS 

By default, thedarkest two percent of ali pixels are mapped to Plack, and the lightest onepercent aremapped to white. You 
can overridethesepercentagesPyusing the -bpercent and -wpercent flags, or you can specify the exact pixel valuesto Pe 
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mapped by using the -bvaiue and -wvaiue flags. Appropriate numbersfor the flagscan begotten from thepgmhist tool. If 
youjustwantto enhancethecontrast, then choosevaluesatelbowsin thehistogram; forexample, if value 29 represents3 
percentof theimagebut value30 represents20 percent, choose3o for bvaiue. If you want to lighten theimage, then set 
bvaiue to 0 and just f iddi e with wvaiue; si mi larly, to darken theimage, set wvaiue to maxvai and play with bvaiue. 

Ali flagscan be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pgmhist(l), ppmnorm(l), pgm(5) 

AUTHOR 

P arti al ly based on thetbnorm fi Iter in M ichael M auldinVFuzzy Pixmap" package. 
Copyright© 1989 byjef Poskanzer. 

28 February 1989 

pgmoil 

pgmoii— Turn a portablegraymap into an oil painting 
SYNOPSIS 

pgmoil [ -n N ] [ p g mf i I e ] 

D ESC RIFIO N 

pgmoii reads a portablegraymap as input, doesan "oil transfer," and writes a portablegraymap as output. 

The oil transfer isdescribed in Beyond Photography by H olzmann, Chapter 4, photo 7. It'sa sortof localized smearing. 

OPTIONS 

T he optional -n flag controis the size of the area smeared. T he default value ÌS3. 
BUGS 

Takesalongtimetorun. 
SEEALSO 

pgmbentley(l), ppmrelief(l), pgm(5) 

AUTHOR 

Copyright© 1990 by Wilson Bent(whb@hoh-2. att.com). 

11 January 1991 

pgmramp 

pgmramp— G en erate a grayscale ramp 
SYNOPSIS 

pgmramp -lr|-tb ] - rectangle | -ellipse width beight 

DESCRIPTION 

pgmramp generates a graymap of thespecified size contai ni ng a black-to-whiteramp. Theseramps are useful for multi plying 
with otherimages, using the pnmarith tool. 



pgmtexture 




OPTIONS 

-Ir 
-tb 

■rectangle 
-ellipse 

Ali flags can 
SEEALSO 

pnmarith(l), pgm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

24 N ovember 1989 

pgmtexture 

pgmtexture— Calculatetextural featureson a portablegraymap 
SYNOPSIS 

pgmtexture [ -d d ] [ p g mf ile] 

DESCRIPTION 

pgmtexture readsa portable graymap asinput. C alculates textural featuresbased on spati al dependencematricesatO, 45, 90, 
and 135degreesforadistanced (default = 1). Textural features include 

(1) Angular Second M oment 

(2) Contrai 

(3) Correlation 

(4) Vari ance 

(5) Inverse D ifferenceM oment 

(6) Sum Average 

(7) SumVariance 

(8) Sum Entropy 

(9) Entropy 

(10) D ifferenceVariance 

(11) D ifferen ce Entropy 

(12, 13) I nformation M easures of C orrelation 
(14) Maximal Correlation Coefficient 

Algorithm taken from "Textural Features for ImageClassification," IEEE Transactionson Systems M an, and Cybertinetics, 
R.M . H aralick, K. Shanmugam, and I. D instein, 1973. SM C-3(6):610-621. 

BUGS 

Theprogram can run incredibly slowlyfor large i m ages ( I arger than 64x64) and command-lineoptionsarelimited. The 
method for fi nding the maximal correlation coefficient, which requi res fi nding the second largest eigenvaiue of amatrixQ, 
does not always converge. 

REFERENCES 

IEEE Transactionson Systems M an, and Cybertinetics SM C-3(6):610-621. 



A leftto nght ramp 
A top to botto m ramp 
A rectangular ramp 
An elliptical ramp 

be abbrevi ated to their shortest unique prefix. 
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SEEALSO 

pgm(5), pnmcut(l) 

AUTHOR 

Copyright© 1991 by T exas A gri cu I tu ral Experi ment Station, employer-for-hireof James Darrell M cCauley. 

22 AuguSt 1991 

pgmtofs 

pgmtof s— C onvert portable graymap to U senix FaceSaver format 
SYNOPSIS 

pgmtofs [ p g mf i I e ] 

D ESC RIPTIO N 

pgmtofs reads a portable graymap as input. Produces U senix FaceSaver format as output. 
FaceSaver isa regi stered trademark of M etron Computerware Ltd. of Oakland, CA. 

SEEALSO 

fstopgm(l), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

18 May 1990 

pgmtolispm 

pgmtoiispm—C onvert a portable graymap into Lisp machine format 
SYNOPSIS 

pgmtolispm [pgmfile] 

DESCRIPTION 

pgmtolispm reads a portable graymap as input and produces a Lisp machine bitmap as output. 

Thisis the file format read by thetv:read-t>it-array-fiie function on TI Explorer and Symbolics Lisp machines. 

Given a PGM (instead of a PBM ), a multiplane image will be output. Thisisprobably not useful unlessyou havea color 
Lisp machine. 

M ultiplanebitmapson Lisp machines are color; buttheiispm image fi le format does not include a colormap, so it must be 
treated as a graymap instead. Thisis unfortunate. 

SEEALSO 

lispmtopgm(l), pgm(5) 

BUGS 

Output width isalwaysrounded up to thenearest multiple of 32; thismight not alwaysbewhatyou want, but it probably is 
(arraysthat are not modulo 32 cannot bepassed to theiispm bitblt function, and thuscannot easily bedisplayed on thescreen). 

N o color. 



pgmtopbm 



AUTHOR 

Copyright© 1991 byJamieZawinski andjef Poskanzer. 

6 M arch 1990 



pgmtopbm 

pgmtopbm— Con vert a portablegraymap into a portable bitmap 
SYNOPSIS 

pgmtopbm [ -f loyd | -f s| -threshold | -hilbert | -dither8 | -d8J -cluster3 
| -c3| -cluster4| -c4 ] -cluster8| -c8] [ -value vai ][-clump si ze ] [pgmf i I e ] 

D ESC RIFIO N 

pgmtopbm reads a portable graymap as input and produce a portable bitmap as output. 

N otethat thereisno pbmtopgm converter because any pgm program can read PBM files automagically. 

OPTIONS 

T he default quantization method isboustrophedonic F I oyd- Sta n berg erro r diffusi on (-tioyd or -fs). Also availableare 
si mplethresholding( -threshold); Bayer's ordered dither ( -dithers) with a 16x16 matrix; and threedifferent sizesof 45- 
degree clustered-dot dither (-ciuster3, -ciuster4, -ciusters). A space-filling curve halftoning method using the H ilbert 
curveisalso available. (-hiibert). 

Floyd-Stei nberg wi II almost alwaysgivethebest looki ng results; however, lookinggood isnot alwayswhat you want. For 
instance, thresholding can beused in a pi pel ine with thepnmconvoi tool, fortasks likeedgeand peak detection. And 
clustered-dot dithering gives a newspaper-like look, auseful special effect. The -vaiue flagalters the thresholding value for 
FI oyd- Stein berg and si mple thresholding. It should bea real number between 0 and 1. Above0.5 meansdarker images; 
below 0.5 meanslighter. 

The H ilbert curve method isuseful for processing images before display on devicesthat do not render individuai pixels 
disti nctly (li ke laser printers). T hi s dithering method can give better results than the ditheri ng usually doneby the laser 
printersthemselves. The -ciump flag alters the number of pixels in a dump. Thisis usually an integer between 2 and 100 
(default 5). Smaller dump sizessmeartheimagelessand arelessgrainy, but seem to loose some grayscale linearity. Typically, 
a PGM imagewill haveto bescaled to fit on a laser printer page (2400 x 3000 pixels for an A4 300dpi page), and then 
dithered to a PBM image before bei ngconverted to a PostScript fi le. A printing pi pel ine mi ght look something likethis: 

pnmscale -xysize 2400 3000 image. pgm ] pgmtopbm -hil ] pnmtops -scale 0.25 image. ps 

Ali flags can be abbrevi ated to their shortest unique prefix. 
REFERENCES 

Theonly referenceyou need for thisstuff is Digital H alftoningby Robert U lichney, M IT Press, ISBN 0-262-21009-6. 

The H ilbert curve space fi Ili ng method istaken from "D igital H alftoning with Space Filling Curves" by LuizVelho, 
ComputerGraphicsVolume25, Number 4, proceedingsof SIGRAPH '91, page 81. ISBN 0-89791-436-8 

SEE ALSO 

pbmreduce(l), pgm(5), pbm(5), pnmconvol(l), pnmscale(l), pnmtops(l) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer. 



26 July 1988 
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pgmtoppm 

pgmtoppm— Colorize a portable graymap into a portable pixmap 
SYNOPSIS 

pgmtoppm col or s pec [pgmf i I e ] 

pgmtoppm col orspecl -col orspec2 [pgmf i I e ] 

pgmtoppm -map mapfile [pgmf il e] 

D ESC RIPTIO N 

pgmtoppm reads a portable graymap as input, colori zesit by multiplying thegray valuesby specified color or colors, and 
produce a portable pixmap as output. 

Ifonlyone color is specified, black in the PGM fi le stays black and whitein the PGM fileturnsinto the specified color in 
the PPM file If two colors (separated by a hyphen) are specified, then black gets mapped to the first color and whitegets 
mapped to thesecond. 

Thecolorcan be specified in fiveways: 

■ A name, assumingthat a pointer to an Xll-style color namesfilewascompiled in. 

■ An Xll-style hexadeci mal specifier: rgb:r/g/b, where r, g, and b areeach 1- to 4-digit hexadecimal numbers. 

■ An Xll-styledecimal specifier: rgbi:r/g/b, where r, g, and b are floati ng-poi nt numbers between 0 and 1. 

■ For backwards COmpatibility, an Old-X 11-Style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, Or#rrrrggggbbbb. 

■ For backwards compatibility, atriplet of numbers separated by commas: r,g,b, where r, g, and b are floati ng-poi nt 
numbers between 0 and 1. (Thisstylewasadded beforeM IT carne up with thesimilar rgbi style.) 

Also, the -map flag letsyou specify an entirecolormap to beused. The mapfile is just a PPM file; it can beany shape, ali that 
mattersis the colors in it and theirorder. In thiscase, black gets mapped to the first color in the mapfile, and whitegets 
mapped to thelast. 

SEE ALSO 

rgb3toppm(l), ppmtopgm(l), ppmtorgb3(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

11 January 1991 

pi1 toppm 

putoppm— Con vert an Atari DegasPll into a portablepixmap 
SYNOPSIS 

piltoppm [pi lf i I e ] 

D ESC RIFIO N 

pii toppm reads an Atari D egas P 1 1 f i le as i n put and produces a portabl e pi xm ap as output. 
SEE ALSO 

ppmtopil (1), ppm(5), pi3topbm(l), pbmtopi3(l) 

AUTHORS 

Copyright© 1991 by Steve Belczyk (seb3egte.com) and Jef Poskanzer. 

19 July 1990 



pi cttoppm 



pi3topbm 

pi3topbm— C onvert an Atari D egas PI 3 fi le i nto a portabl e bi tmap 



SYNOPSIS 

pi3topbm [pi 3f i I e] 

D ESC RIPTIO N 

pi3topbm reads an Atari D egas PI3 file as input. Produces a portable bitmap as output. 
SEEALSO 

pbmtopi3(l), pbm(5), piltoppm(l), ppmtopil(l) 

AUTHORS 

Copyright® 1988 by David Beckemeyer (bdtidavid) and D iomidisD . Spi nellis. 

11 M ardi 1990 

picttoppm 

picttoppm— C onvert a M acintosh PICT fileinto a portable pixmap 
SYNOPSIS 

picttoppm [ -verbose] [ -fullres] [ -noheader] [ -quickdraw] [ -f ontdirf ile] [pi et f i I e ] 

D ESC RIFIO N 

picttoppm reads a PICT file(version 1 or 2) and outputs a portable pixmap. Useful as the first step in converti ng a scanned 
imageto somethingthat can bedisplayed on U N IX. 

OPTIONS 

-tontdir file M ake the list of BD F fonte in n i e availablefor useby pict-toppm when drawingtext. F or the format of 

thetontdir file, seethe"fontdir File Format" subsection. 
-fuiires Force any imagesin the PICT fileto be output with at least the r full resolution. A PICT filemay indicate 

that a contai ned imageisto bescaled down before output. T hi s opti on forcesimagesto retain theirsizes 

and prevent information loss. Useof thisoption disablesall PICT operationsexcept images. 
-noheader Do not skip the 512-byte header that ispresent on ali PICT files. Thisis useful when you havePICT data 

that wasnot sto red in the data fork of a PICT file, 
-quickdraw Execute only pure quickdraw operations. In particular, turn off theinterpretation of special PostScript 

printer operations. 

-verbose Turnson verbose mode, which printsawholebunch of information that only picttoppm hackers really 

care about. 

BUGS 

ThePICT fileformatis a general drawing format, picttoppm doesnot support ali thedrawingeommands, but itdoeshave 
full support for any imagecommandsand reasonable support for line, rectangle, polygon, and text drawing. It is useful for 
converting scanned images and some drawing conversion. 

M emory isused very liberally with at least six bytesneeded for every pixel. Large bitmap PICT files wi II likely run your 
computer out of memory. 




Parti: U ser Commands 



fontdir FILE FORMAT 

picttoppm hasabuilt-in default font and your locai installer probably provided adequate extra fonts. You can pointpicttoppm 
at morefontsthatyou specify in a font directory file. Each line in thefileiseither a comment line which must begin with #, 
or font informati on. The font information consistsof four whitespaceseparated fi elds. The first is the font number, the 
second isthefontsizein pixels, thethird is the font style, andthefourth isthenameof aBDF filecontainingthefont. The 
BD F format isdefi ned by theX Window System and is not described here. 

The font number indicates the type face. H ere isa list of known font numbersand theirfaces. 



0 


Chicago 


1 


Application font 


2 


New York 


3 


Geneva 


4 


M onaco 


5 


Veni ce 


6 


London 


7 


Athens 


8 


San Francisco 


9 


Toronto 


11 


Cairo 


12 


LosAngeles 


20 


TimesRoman 


21 


H elvetica 


22 


Courier 


23 


Symbol 


24 


Taliesin 



The font style indicates a variati on on the font. M ulti pie vari ationsmay apply to a font and the font style is the sum of the 
variation numbers, which are 



1 


Boldface 


2 


Italie 


4 


Underlined 


8 


Outlined 


16 


Shadow 


32 


Condensed 


64 


Extended 



Obviously, the font definitionsarestrongly related to theM acintosh. M ore font numbersand information about fonts can 
befound in M acintosh documentation. 

SEEALSO 

Inside M acintosh volumesl and 5, ppmtopict(l), ppm(5) 

AUTHOR 

Copyright ©1993 George Phillips. 

29 N ovember 1991 



pnmalias 

pjtoppm 

pjtoppm— Convert an HP PaintJ et file to a portable pixmap 
SYNOPSIS 

pjtoppm [pai nt j et ] 

D ESC RIPTIO N 

pjtoppm readsan H P PaintJet file as input and converts it into a portable pixmap. Thiswas a quick hack to savesometrees, 
and it only handlesa small subset of thepaintjet commands In particular, it will only handleenough commandsto convert 
most raster imagefiles. 

REFERENCES 

H P PaintJ et XL Color G raphicsPrinter U ser's G uide 

SEEALSO 

ppmtopj(l) 

AUTHOR 

Copyright© 1991 by C hristos Zoulas. 

14 July 1991 

pktopbm 

pktopbm— Convert packed (PK) format font into portable bitmap(s) 
SYNOPSIS 

pktopbm pkfile[.pk] [-c num] pbmfile ... 

DESCRIPTION 

pktopbm reads a packed (PK) font file as input and produces portable bitmapsas output. If the filename "-" isused for any of 
thefilenames, the standard input stream (or standard output where appropriate) will beused. 

OPTIONS 

-c num Setsthecharacter number of thenext bitmap written to num. 
SEEALSO 

pbmtopk(l), pbm(5) 

AUTHOR 

Adapted from Tom Rokicki'spxtopk by Angus Duggan (ajcd@dcs.ed.ac.uk). 

6 August 1990 

pnmalias 

pnmaiias— Anti alias a portable anymap. 
SYNOPSIS 

pnmalias [ -bgcolor cot or ] [ -fgcolor col or ] [ -bonly] [ -fonly] [ -balias] [ -falias] 
[ -weight w] [pnmf i I e ] 
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D ESC RIFIO N 

pnmaiias reads a portable anymap as input and applies antialiasing to background and foreground pixels. If the input file is a 
portable bitmap, the output antialiased imageispromoted to a graymap, and a messageisprinted informing the user of the 
change in format. 

OPTIONS 

-bgcoior col or b, Set the background color to coi or b, and the foreground to color to coi orf . Pixels with thesevalues 
-fgcoior col orf will be antialiased. By default, the background color istaken to beblack, and foreground color is 

assumed to bewhite. Thecolorscan bespecified in fiveways: 

■ A name, assumingthat a pointer to an Xll-style color namesfilewascompiled in. 

■ An Xll-style hexadeci mal specifier: rgb:r/g/b, where r, g, and b areeach 1- to 4-digit 
hexadecimal numbers. 

■ An Xll-styledecimal specifier: rgbi:r/g/b, wherer, g, and b are floati ng-poi nt numbers 
between 0 and 1. 

■ For backwards compatibility, an old-Xll-style hexadecimal number: #rgb, #rrggbb, 

#rrrgggbbb, Or #rrrrggggbbbb. 

■ For backwards compatibility, atripletof numbers separated bycommas: r,g,b, wherer.g, 
and b are floati ng-poi nt numbers between 0 and 1. (Thisstylewasadded beforeM IT carne 
up with thesimilar rgbi style.) 

N otethat even when dealing with graymaps, background and foreground colorsneed to bespecified in the fashion described 
in the precedi ng list. In thiscase, background and foreground pixel valuesaretaken to bethevalueof thered component for 
thegiven color. 

-boniy, -foniy Apply antialiasing only to background (-boniy), or foreground (-foniy) pixels. 

-baiias, -f alias Apply anti al iasi ng to ali pixels surrounding background (-baiias), or foreground (-f alias) pixels. 

By default, antialiasing takes place only among neighboring background and foreground pixels. 
-weight w Use» asthe centrai weight for the aliasi ng fi Iter, w must bea real number in therangeO <w <1. 

Thelowerthevalueofw is, the "blurrier" the output i mage is. The default isw = 1/3. 

SEEALSO 

pbmtext(l), pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright© 1992 by Alberto Accomazzi, Smithsonian Astrophysical Observatory. 

30 Aprii 1992 



pnmarith 

pnmarith— Perform ari thmetic on two portable anymaps 
SYNOPSIS 

pnmarith -add | -subtract | -multiply | -diff erence pnmfilel p n mf I I e 2 

D ESC RIFIO N 

pnmarith readstwo portable anymaps as i nput, performs the specified arithmetic operation, and produces a portable anymap 
as output. The two input anymaps must bethesamewidth and height. 

The arithmetic is performed between corresponding pixels in thetwo anymaps, as if maxvai wasi .0, biack wasa.a, with a 
linear scale in between. Results that fall outsideof [0..1) aretruncated. 



pnmcomp 




Theoperator -difference calculates the absolute value of 

pnmarith -subtract pnmfilel p n m- f i I e 2 

In otherwords, notruncation isdone. 

Ali flagscan be abbreviateci to their shortest unique prefix. 

SEEALSO 

pbmmask(l), pnmpaste(l), pnminvert(l), pnm(5) 

AUTHOR 

Copyright© 1989, 1991 byjef Poskanzer. Lightly modified by M arce! W ijkstra (wijkstraiafwi.uva.nl). 

26 August 1993 

pnmcat 

pnmcat— C oncatenate portable anymaps 
SYNOPSIS 

pnmcat [ -white j -black] -leftright j -Ir [ - j top | - j bottoni ] pnmfile pnmfile ... 
pnmcat [ -white | -black] -topbottomj -tb [ - jleft ] - jright] pnmfile pnmfile ... 

D ESC RIPTIO N 

pnmcat reads portable anymaps as input, concatenatesthem either left to right or top to bottoni, and produce a portable 
anymap as output. 

OPTIONS 

If the anymaps are not ali thesameheight (left-right) orwidth (top-bottom), the smaller oneshaveto bejustified with the 
largest. By default, they get centered, butyou can specify one side or the other with oneof the -j* flags. So, -topbottom - 
jieft would stack the anymaps on top of each other, flush with the left edge. 

The -white and -black flags specify which color to use to fili in the extra spacewhen doingthisjustification. If neither is 
specified, the program makesaguess. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

12 M ardi 1989 

pnmcomp 

pnmcomp— Composite two portable anymap filestogether 
SYNOPSIS 

pnmcomp [ -invert] [ -xoffN] [-yoffN] [ -alphapgmf ile] overlay [pnm- i nput ] [pnm- cut put ] 
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D ESC RIFIO N 

pnmcomp reads i n a portable anymap imageand puts an overlay upon it, with optional alpha mask. The -aiphapgmfìie allows 
you to also add an alpha mask fileto thecompositing process; therangeof max and min can beswapped by using the -invert 
option. The -xoff and -yoff argumentscan be negative allowingyou to shift the overlay off the top corner of thescreen. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1992 by David Koblas(kobias?mips.com). 

21 February 1989 

pnmconvol 

pnmconvoi— General mxn convoluti on on a portable anymap 
SYNOPSIS 

pnmconvol convol ut i onf il e [ p n mf ile] 

D ESC RIFIO N 

pnmconvol readstwo portable anymapsas input, convolvesthesecond using the first, and writes a portable anymap as output. 

Convoluti on meansreplacing each pixel with aweighted averageof thenearby pixel s. Theweightsand the area to averageare 
determi ned by theconvolution matrix. Theunsigned numbersin theconvolution fi le are offset by -maxvai/2 to makesigned 
numbers, andthen normalized, sotheactual values in theconvolution file are only relative. 

H ereisasampleconvolution file; it does a simple averageof the nine immediate neighbors, resulting in asmoothed image 

P2 
3 3 
18 

10 10 10 
10 10 10 
10 10 10 

To seehow thisworks, do the offset menti oned in the precedi ng paragraph: 10 - 18/2 givesl. The possi blerangeof values is 
from 0 to 18, and after the offset that's-9 to 9. Thenormalization step makestherange-1 to 1, and the values get scalee! 
correspondingly so they becomel/9— exactly what you want. The equi valent matrix for 5x5 smoothing would havemaxvai 
50 and be fi lied with 26. 

Theconvolution fi le wi II usually bea graymap, so that thesameconvolution isapplied to each color component. H owever, if 
you wantto use a pixmap and do a different convolution to differentcolors, you can certainly do that. 

SEE ALSO 

pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright© 1989, 1991 byjef Poskanzer. 

13 January 1991 
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pnmcrop 

pnmcrop— C rop a portable anymap 
SYNOPSIS 

pnmcrop [ -white ] -black] [ -left] [ -right] [ -top] [ -bottom] [pnmf i I e ] 

D ESC RIPTIO N 

pnmcrop reads a portable anymap as input, removesedgesthat are the background color, and produces a portable anymap as 
output. 

OPTIONS 

By default, it makes a guess as to what the background color is. You can override the default with the -white and -biack flags. 

Theoptions -left, -right, -top and -bottom restrict croppingto the si des speci fi ed. The default isto crop ali sidesof the 
image. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pnmcut(l), pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

25 Februaryl989 

pnmcut 

pnmcut— C ut a rectangle out of a portable anymap 
SYNOPSIS 

pnmcut x y width height [pnmfile] 

DESCRIPTION 

pnmcut reads a portable anymap as input, extractsthespecified rectangle, and produces a portable anymap as output. Thex 
and y can be negative, in which casethey are i nterpreted relative to the right and bottom of the anymap, respectively. 

SEEALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

21 February 1989 

pnmdepth 

pnmdepth— Change the maxvai in a portable anymap 
SYNOPSIS 

pnmdepth newmaxval [pnmfile] 
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D ESC RIFIO N 

pnmdepth reads a portable anymap as input, scales ali the pixel values, and writesouttheimagewith thenew maxvai. Scali ng 
the colors down to a smaller maxvai will result in somelossof information. 

Becareful of off-by-oneerrorswhen choosing thenew maxvai. For instance, if you want the color values to befivebitswide, 

use a maxvai Of 31, not 32. 

SEEALSO 

pnm(5), ppmquant(l), ppmdither(l) 

AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. 

12 January 1991 

pnmenlarge 

pnmeniarge— Read a portable anymap and enlarge it N times 
SYNOPSIS 

pnmenlarge N [ p n mf i I e ] 

D ESC RIFIO N 

pnmenlarge reads a portable anymap as input, replicates itspixelsN times, and produces a portable anymap as output. 

pnmenlarge can only enlarge by i nteger factors. T he slower but more general pnmscaie can enlarge or reduce by arbitrary 
factors, and pbmreduce can reduce by i nteger factors, but only for bitmaps. 

If you enlarge by afactor of 3 or more, you should probably add a pnmsmootn step; otherwise, you can see the originai pixels 
in the resulti ng image. 

SEEALSO 

pbmreduce(l), pnmscale(l), pnmsmooth(l), pnm(5) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer. 

26 February 1989 

pnmfile 

pnmf ne— Descri bea portable anymap 
SYNOPSIS 

pnmfile [pnmf i i e ] ... 

DESCRIPTION 

pnmfile reads one or more portable anymaps as input and writes out short descri ptions of the image type, size, and so on. 
This is mostly for use in shell scripts, sotheformatisnot parti cularly pretty. 

SEEALSO 

pnm(5), file(l) 



pnmgamma 



AUTHOR 

Copyright© 1991 byjef Poskanzer. 

9 January 1991 

pnmflip 

pnmfiip— Perform oneormoreflip operationson a portableanymap 
SYNOPSIS 

pnmflip [ -lef t right ] -Ir] [ -topbottomi -tb] [ -transpose! -xy] [ -rotate90| -r90| -ccw ] 
[ - rotate270 1 - r270 1 - cw ] [ - rotatel 80 j - r1 80] [p nmf i I e ] 

DESCRIPTION 

pnmflip reads a portableanymap as input, performsoneor moreflip operations in theorder specified, and writesout a 
portableanymap. 

OPTIONS 

T he fi ip operati onsavailable are leftfor right ( -ìeftnght or -ir); topfor bottom (-topbottom or -tb); and transposition (- 
transpose or -xy). I n addition, somecanned concatenati ons are avai labi e -rotate9oor -ccw isequivalentto -transpose - 

topbottom; -rotate270 Or -cw ÌS equi vai ent tO -transpose -leftright; and -rotate180 ÌS equi valent tO -leftright -topbottom. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pnmrotate(l), pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

25 July 1989 

pnmgamma 

pnmgamma— Perform gamma co rrection on a portableanymap 
SYNOPSIS 

pnmgamma vai ne [ p n mf i I e ] 

pnmgamma redvalue greenvalue bluevalue [ p n mf i I e ] 

DESCRIPTION 

pnmgamma reads a portable anymap as input, performs gamma correction, and produces a portableanymap as output. 

Theargumentsspecify what gamma value(s) to use A valueof 1.0 leaves the image alone, lessthan 1 darkensit, and greater 
than 1 lightensit. 

SEEALSO 

pnm(5) 

AUTHOR 

Copyright© 1991 by Bill Davidson and Jef Poskanzer. 

12 January 1991 
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pnmhistmap 

pnmhistmap— Drawahistogram foraPGM orPPM file 
SYNOPSIS 

pnmhistmap [ -black] [ -white] [ -max N ] [ - verbose ] [ p n mf i le] 

D ESC RIFIO N 

pnmhistmap reads a portable anymap as input, although bitmap (PBM ) input produce an errar messageand no image, and 
producesan image showing a histogram of the color (or gray) values in the input. A graymap (PGM ) input producesa 
bitmap output. A pixmap (PPM ) input producespixmap output with threeoverlaid histograms: a red onefor thered input, 
a green onefor the green input, and a blue onefor the blue input. The output isfixed in size 256 pixelswideby 200 pixels 
high. 

0PTI0NS 

-biack Ignoresthecount of black pixels when scali ng the histogram. 
-white Ignoresthecount of white pixels when scaling the histogram. 

The -biack and -white options, which can beused separately or together, areuseful for imageswith alargepercentageof 
pixels whosevalue iszero or 255, which can cause the remai ni ng histogram datato becomeunreadably small. N otethat, for 
pixmap inputs, these options applyto ali colors; if, for example, the input hasa largenumber of bright-red areas, you will 
probably wantto use the -white option. 

-max n Forcethescalingof thehistogram to useN asthelargest-count value. Thisisuseful for inputswith a large 

percentage of single-color pixels that are not black or white. 
-verbose Report the progress of making the histogram, includi ng the largest-count value used to scale the output. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
BUGS 

Assumes maxvai is always 255. Imageswith asmaller maxvai will only use the lower-value si de of the histogram. This can be 
overcomeeither by pipingtheinputthrough pnmdepth 255 or by cutting and scali ng the lower-value side of thehistogram. 
N either is a parti cularly elegant solution. 

Should allow the output sizeto be specified. 
SEEALSO 

pgmhist(l), ppmhist(l), pgm(5), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whbuusc.edu). 

25 October 1993 

pnmindex 

pnmindex— Build avisual index of a bunch of anymaps 
SYNOPSIS 

pnmindex [-size N][-across N][-colors N][-black] pnmfìle ... 

D ESC RIFIO N 

This script makes small versions of abunch of anymaps, addslabels, and concatenatesthem togetherinto a collage. 



pnmmargi n 




OPTIONS 

-size Controls how bigeach imagebecomes; the default is 100x100. 
-across Controlshow many imagesarein each row; the default issix. 

-coiors Controls how many colors the final index getsquantized to, if quantization isnecessary; the default ÌS256. 
-biack C ontrols the color of the paddi ng between theimages; normally it'swhiteand the labels are black lettering on 
white background, butthe -biack flag reversesthis. 

SEEALSO 

pnmscale(l), pnmcat(l), pbmtext(l), ppmquant(l), pnm(5) 

BUGS 

It'svery slow. 

It'sa csh script, csh seri pts are not portableto System V. Scripts in general arenot portableto non-UN IX environments. 

AUTHOR 

C opyright © 1991 by J ef Poskanzer. 

9 January 1991 

pnminvert 

pnminvert— I nvert a portable anymap 
SYNOPSIS 

pnminvert [ p n mf il e ] 

D ESC RIFIO N 

pnminvert reads a portable anymap as input, inverts it black for white, and produces a portable anymap as output. 
SEEALSO 

pnm(5) 

AUTHOR 

C opyright © 1989 by J ef Poskanzer. 

8 August 1989 

pnmmargin 

pnmmargin— Add a borderto a portable anymap 
SYNOPSIS 

pnmmargin [ -white j - black | -color col orspec ] size [ p n mf ile] 

D ESC RIFIO N 

pnmmargin reads a portable anymap as input, addsa border of the speci fi ed number of pixels, and produces a portable anymap 
as output. 
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OPTIONS 

You can specify the border color with the -white, -biack, and -color flags. If no color is specified, the program makesa 
guess. 

SEEALSO 

pnm(5) 

BUGS 

It's a script. Scripts are not portableto non-U N IX environments. 

AUTHOR 

C opyright © 1991 by J ef Poskanzer. 

9 January 1991 

pnmnlfilt 

pnninifiit-N onli near fi Iters: smooth, alphatrim mean, optimal estimation smoothing, edgeenhancement. 
SYNOPSIS 

pnmnlfilt alpha radius [pnmfilc] 

DESCRIPTION 

This is somethi ng of aSwissarmy knifefilter. It hasthree disti net operati ng modes. In ali of themodes, each pixel in the 
imageisexamined and processed accordi ngto itand itssurrounding pixels values. Ratherthan usi ng the ni ne pixels in a3x3 
block, seven hexagonal area samplesaretaken, thesizeof thehexagonsbeing controlied by the radius parameter. A radius 
valueof 0.3333 meansthat the seven hexagonsexactly fit into the center pixel (that is, therewill be no fi Iteri ng effect). A 
radius valueof 1 .0 meansthat the seven hexagonsexactly fit a 3x3 pixel array. 

ALPHA-TRIMMED MEAN FILTER (0.0 < = alpha < = 0.5) 

The valueof the center pixel will bereplaced by the mean of the seven hexagon values, but the seven values are sorted by size 
and the top and bottoni alpha porti on of the seven areexcluded from the mean. This implies that an alpha valueof 0.0 gives 
the samesortof output asanormal convolution (thatis, averaging or smoothing filter), where radius will determinethe 
"strength" ofthefilter. A good valueto start from for subtlefiltering isaipha = 0.0, radius = 0.55. Fora more blatant effect, 

try alpha = 0.0 and radius =1.0. 

An alpha valueof 0.5 will cause the medi an valueof the seven hexagonsto beused to replace the center pixel value. Thissort 
of filter isgood for eli mi nati ng "pop" or single pixel noisefrom an imagewithout spreading thenoiseout or smudging 
featureson theimage. Judicious use of the radius parameter will fi ne-tune the fi Iteri ng. I ntermediate values of alpha give 
effeets somewhere between smoothing and "pop" noisereduction. For subtlefiltering, try starti ng with values of alpha = 0.4, 
radius = 0.6. For a more blatant effect, try alpha = 0.5, radius = 1.0. 

OPTIMAL ESTIMATION SMOOTHING. (1.0 < = alpha < = 2.0) 

This type of fi Iter appli es a smoothing fi Iter adaptively over theimage. For each pixel, thevarianceof thesurrounding 
hexagon values is cai cu lated, and the amountof smoothing ismadeinversely proportional to it. T he idea is that if the 
variance issmall, then it isdueto noise in theimage, whi le if the vari ance is large, it isbecauseof "wanted" imagefeatures. 
As usuai, the radius parameter controis the effecti ve radius, but it probably advisableto leave the radius between 0.8 and 1 .0 
for the variance calculation to bemeaningful. The alpha parameter sets the noise threshold, over whi eh less smoothing will 
bedone. This meansthat small values of alpha will give the most subtlefiltering effect, whi le large values will tend to smooth 
ali partsof theimage. You could start with values li ke alpha = 1.2, radius = 1 .0 and try increasi ng or decreasing the alpha 
parameter to get the desi red effect. This type of filter isbest for fi Iteri ng out dithering noise in both bitmap and color images. 



pnmnoraw 

EDGE ENHANCEMENT. (-0. 1 > = alpha > = -0.9) 

This is the opposite type of filter to the smoothing filter. It enhances edges. T he alpha parameter controis the amount of 
edgeenhancement, from subtle {-o. 1) to blatant (-0.9). The radius parameter controis the effettive radius as usuai, but 
useful valuesarebetween 0.5 and 0.9. Try starti ngwith valuesof alpha = 0.3, radius = 0.8. 

COMBINATICI USE 

The vari ous modes of pnmnif ut can beused one after the otherto get the desi red result. For instanceto turn a monochrome 
dithered imageinto agrayscaleimage, you could try oneortwo passesof the smoothing fi Iter, followed by a pass of the 
opti mal estimation filter, then some subtle edgeenhancement. N otethat usi ng edgeenhancement isonly likely to be useful 
after oneof the nonlinear filters (alpha-tri mmed mean or opti mal estimation filter), as edgeenhancement is the direct 
opposite of smoothing. 

For reduci ng color quantization noisein images (that is, turni ng GIF filesback into 24- bit files), you could try a pass of the 
opti mal estimation filter (alpha 1 .2, radius 1 .0), a pass of the median filter (alpha 0.5, radius 0.55), and possi bly a passof 
the edgeenhancement filter. Several passesof the opti mal estimation filter with deci i ni ng alpha valuesaremoreeffectivethan 
a single pass with a large alpha value. As usuai, thereisatradeoff between fi Iteri ng effectivenessand loosing detail. Experi- 
mentation isencouraged. 

REFERENCES 

The alpha-tri mmed mean filter isbased on the descri ption inlEEECG&A,May 1990, page 23, by M ark E. Lee and Richard 
A. Redner, and hasbeen enhanced to allow continuous alpha adjustment. 

The opti mal estimation filter istaken from an arti de "Converti ng D ithered Images Back to Grayscale" by Alien Stenger, Dr. 
Dobb's Journal, N ovember 1992, and this article references "Digital ImageEnhancementand NoiseFi Iteri ngby Use of Locai 
Stati stics" byJong-Sen Lee, IEEE Transactionson Pattern Analysisand M achine Intelligence, M arch 1980. 

The edgeenhancement details are from pgmenhance(l), which istaken from Philip R. Thompson'sxim program, which in 
turn took it from Section 6 of "D igital H alftonesby Dot D iffusion" by D . E. Knuth, ACM Transaction on Graphics Voi. 6, 
N 0. 4, October 1987, which in turn got it from two 1976 papersbyj. F. Jarviset al. 

SEEALSO 

pgmenhance(l), pnmconvol(l), pnm(5) 

BUGS 

Integers and tables may overflow if ppmjaxmaxval is greater than 255. 
AUTHOR 

GraemeW. Gill (graemeWabtam.oz.au). 

5 February 1993 

pnmnoraw 

pnmnoraw— Force a portable anymap i nto piai n format 
SYNOPSIS 

pnmnoraw [ p n mf ile] 

D ESC RIFIO N 

pnmnoraw reads a portable anymap as input and writesit out in piai n (nonraw) format. This isfairly useless if you haven't 
defined the pbmplus_rawbits compi le- ti me opti on. 
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SEEALSO 

pnm(5) 

AUTHOR 

C opyright © 1991 by J ef Poskanzer. 

8 January 1991 



pnmpad 

pnmpad— Add bordersto portableanymap 
SYNOPSIS 

pnmpad [ -white j -black] [-1#] [-r#] [-t#] [-b#] [pnmfile] 

D ESC RIPTIO N 

pnmpad reads a portable anymap as input and outputsa portableanymap with extra borders of the si zes speci fi ed. The color of 
theborderscan be setto biack or white (default biack). 

SEEALSO 

pbmmake(l), pnmpaste(l), pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 by J ef Poskanzer. 

pnmpaste 

pnmpaste— Paste a rectangle into a portable anymap 
SYNOPSIS 

pnmpaste [- replace | -or ] -and -xor] f r o mp n rmf i I e x y [i ntopnmfi I e ] 

D ESC RIFIO N 

pnmpaste readstwo portable anymapsas input, inserts the first anymap into thesecond at the specified location, and produces 
a portableanymap the samesizeas thesecond as output. If thesecond anymap isnot specified, it isread from stdin. Thex 
and y can be negative, in which casethey are i nterpreted relative to theright and bottom of the anymap, respecti vely. 

Thistool ismost useful in combination with pnmcut. For instance, if you want to edit asmall segment of a largeimage, and 
your image editor cannot edit the largeimage, you can cut out the segment you are i nterested in, edit it, and then paste it 
back in. 

Another useful companion tool ispbmmask. 

Theoptional flag specifies the operation to usewhen doing the paste. Thedefault is -replace. Theother logicai operations 
areonly allowed if both input i mages are bitmaps. These operati onsact as if white is true and black is false. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pnmcut(l), pnminvert(l), pnmarith(l), pnm(5), pbmmask(l) 



pninsale 




AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. 

21 February 1991 

pnmrotate 

pnmrotate— Rotate a portable anymap by some angle 
SYNOPSIS 

pnmrotate [ -noantialìas] angle [pnmfile] 

DESCRIPTION 

pnmrotate reads a portable anymap as input, rotatesit by the speci fi ed angle, and produces a portable anymap as output. If 
the input file is in color, the output wi II be, too; otherwise, it will begrayscale. The angle is in degrees (floating-poi nt), 
measured counter-clockwise. It can be negative, but it should be between -90 and 90. Also, for rotati onsgreater than 45 
degrees you may get better results if you first usepnmfitp to do a90-degreerotation and then pnmrotate lessthan 45 degrees 
back the other direction. 

The rotati on algori thm isAlan Paeth'sthree-shear method. Each shear is implemented by looping over the sourcepixels and 
distri butingfractionsto each of the desti nati on pixels. Thishasan antialiasingeffect— it avoidsjagged edges and similar 
artifacts. H owever, it also meansthat the originai colorsorgray levelsin theimagearemodified. If you need to keep 
preci sely the same set of colors, you can use the -noantialìas flag. Thisdoes the shearing by moving pixels without changing 
their values. If you want anti aliasi ng and don't careabout the precise colors, but stili need a limited -number* of colors, you 
can run the result through ppmquant. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
REFERENCES 

"A Fast Algorithm forGeneral Raster Rotation" byAlan Paeth, Graphics Interface '86, pages 77-81. 
SEE ALSO 

pnmshear(l), pnmflip(l), pnm(5), ppmquant(l) 

AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. 

12 January 1991 

pnmscale 

pnmscaie— Scalea portable anymap 
SYNOPSIS 

pnmscale s [pnmf i I e ] 

pnmscale -xsize j -width ] -ysize ] -height s [pnmfile] 

pnmscale -xscale | -yscale s [pnmfile] 

pnmscale -xscale j -xsize j -width s -yscale| -ysize| -height s [pnmfile] 

pnmscale -xysize x y [pnmfile] 

pnmscale -pixels n [pnmfile] 
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D ESC RIFIO N 

pnmscaie reads a portable anymap as input, scalesit by the specified factor orfactors, and produce a portableanymap as 
output. If the input file is in color, the output wi II be, too; otherwise, it will begrayscale. You can both enlarge (scale factor > 
1) and reduce (scale factor < 1). 

You can specify onedimension as a pixel size, and theother dimension will bescaled correspondingly. 
You can specify onedimension as a scale, and theother dimension will not bescaled. 
You can specify different sizes or scales for each axis. 

You can use the special -xysize flag, which fitstheimageinto the specified size without changing the aspect ratio. 

Or, you can usethe-pixeis flag, which fitstheimageinto the specified number ofpixels without changing the aspect ratio. 

Ali flags can be abbrevi ated to their shortest unique prefix. 

If you enlarge by a factor of threeor more you should probably add apnmsmooth step; otherwise you can see the originai 
pixels in the resulti ng image. 

SEEALSO 

pbmreduce(l), pnmenlarge(l), pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. 

12 January 1991 

pnmshear 

pnmshear— Shear a portable anymap by some angle 
SYNOPSIS 

pnmshear [ -noantialias] angle [pnmfile] 

D ESC RIFIO N 

pnmshear reads a portable anymap as input, shears it by the speci fi ed angle, and produces a portable anymap as output. If the 

input fileis in color, theoutput will betoo; otherwise, itwill begrayscale. Theangleisin degrees(floating-point), and 

measuresthis: 

+ — + + — + 

l!!W 

! OLD| ] \NEW \ 
I ! I an\\ 

+ + |gle+ + 

If the angle is negative, it shears theother way: 

+ + | -an+ + 

lllgi// 

| OLD | |e/ NEW / 

III// 

+ + + + 

The angle should not gettoo closeto 90 or -90, or the resulti ng anymap will beunreasonably wide. 

The shearing is implemented by looping over the source pixels and di stri buti ng fracti ons to each of the desti nation pixels 
Thishasan antialiasing effect— it avoidsjagged edgesand similar arti facts. H owever, it also meansthat the originai colorsor 
gray levels in the image are modified. If you need to keep precisely thesameset of colors, you can use the -noantialias flag. 
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Thisdoes the shearing by moving pixelswithout changing their values. If you want anti aliasing and don't care about the 
precise colors, but stili need a limited *number* of colore, you can run the result through ppmquant. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pnmrotate(l), pnmflip(l), pnm(5), ppmquant(l) 

AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. 

12 January 1991 



pnmsmooth 

pnmsmooth— Smooth out an image 
SYNOPSIS 

pnmsmooth [ p n mf il e ] 

D ESC RIFIO N 

pnmsmooth smoothsout an image by replacing each pixel with the averageof itsnine immediate nei ghbors. It is implemented 
as a simple script using pnmconvoi. 

SEEALSO 

pnmconvol(l), pnm(5) 

BUGS 

It's a script. Scripts are not portableto non-U N IX environments. 
AUTHOR 

Copyright© 1989, 1991 byjef Poskanzer 

13 January 1991 

pnmtile 

pnmtile— Replicate a portable anymap into aspecified size 
SYNOPSIS 

pnmtile width height [pnmfile] 

DESCRIPTION 

pnmtile reads a portable anymap as input, replicatesit until it isthespecified size, and produces a portable anymap asoutput. 
SEEALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

13 May 1989 
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pnmtoddif 

pnmtoddif — C onvert a portable anymap to D D I F format 
SYNTAX 

pnmtoddif pnmtoddif [-resolution x y] [pnmfile [ddiffile]] 

OPTIONS 

resolution x y T he horizontal and valicai resolution of the output i mage in dots per i neh. D efaultsto 78dpi. 
pnmf i i e T he filmarne for the i mage file in PN M format. If thisargument isomitted, input isread from stdin. 

ddiffile The filmarne for the i mage fi le to becreated in DD IF format. If thisargument isomitted, theddi f f i i e is 

written to standard output. It can only specified if a pnmf i i e isalso specified. 

D ESC RIFIO N 

pnmtoddif takes a portable anymap from standard input and convertsit into a DD IF imagefileon standard output or the 
specified DDIF file. 

PBM format (bitmap) data iswritten asl-bit D DIF, PGM format data (grayscale) as8-bit grayscale DDIF, and PPM format 
data iswritten as 8,8,8-bit color DDIF.AII DDIF i mage fi les are written asuncompressed. The data piane organization is 
interleaved by pixel. 

In additi on to thenumber of pixelsin thewidth and heightdimmsion, DDIF imagesalso carry information aboutthesize 
that the i mage should have, that is, thephysical space that a pixel occupies. PBM PLUS imagesdo not carry this information, 
hmeeit hasto beexternally supplied. The default of 78dpi has the beneficiai property of not causi ng a resizeon most D igital 
Equi pmmt Corporation color monitora 

AUTHOR 

Burkhard N eidecker-Lutz 

Digital Equipmmt Corporation, CEC Karlsruhe 

neideck@nestvx.enet.dec.com 

pnmtofits 

pnmtofits— C onvert a portable anymap into FITS format 
SYNOPSIS 

pnmtofits [-max f ] [-min f ] [pnmf i I e ] 

D ESC RIFIO N 

pnmtofits reads a portable anymap as input and producesa FITS (Flexible I mage Tran sport System) fi le as output. The 
resolution of the output fileiseither 8 bits/pixel, or 16 bits/pixel, depmding on thevalueof maxvai in the input fi le If the 
input file is a portable bitmap or a portable graymap, the output file consists of a single piane i mage (naxis = 2). If instead 
the input file is a portable pixmap, the output file will consist of a three-plane image (naxis = 3, naxis3 = 3). A full 
description of the FITS format can befound in Astronomy& AstrophysiGSupplement Series44 (1981), page 363. 

OPTIONS 

Flags -min and -max can beused to set datamax, datamin, bscale, and bzero in the FITS header, but do not cause the data to 
be rescaled. 

SEEALSO 

fitstopnm(l), pgm(5) 
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AUTHOR 

Copyright © 1989 by W ilson H . Bent (whb9hoh-2.att.com), with modificati ons by Alberto Accomazzi 

(alberto?cf a . harvard . edu). 

5 Decemberl992 



pnmtops 

pnmtops— C onvert portable anymap to PostScript 
SYNOPSIS 

pnmtops [-scale s ] [ -turn j -noturn] [ -rie | -runlength] [ -dpi n][-width n][-height n] 
[ -center! -nocenter] [ p n mf i I e ] 

DESCRIPTION 

pnmtops reads a portable anymap asinput and producesencapsulated PostScript as output. 

If the input file is in color (PPM ), a color PostScript filegetswritten. Some PostScript interpreterscan't handle color 
PostScript. If you haveoneof these, you will need to run your imagethrough ppmtopgm first. 

Notethatthereisno pstopnmtool; thistransformation isone-way, because a pstopnm tool would be a fui l-fledged PostScript 
interpreter, which isbeyond the scope of this package. H owever, seethepsidtopgm tool, which can read grayscale non-run- 
length PostScript image data. Also, if you're willing to instali the fai rly largeGhostScript package, itcomeswith apstoppm 
script. 

OPTIONS 

The -scaie flag controis the scale of the result. The default scale is 1, which on a 300dpi printer such as the Apple 
LaserWriter makes the output look about the samesizeas the input would if it wasdisplayed on atypical 72dpi screen. To 
get onePN M pixel per 300dpi printer pixel, use -scaie 0.25. 

The - turn and -noturn flags control whether the image getsturned 90 degrees. N ormai ly, if an image iswider than it is tali, 
it getsturned automati rally to better fit the page. If the - turn flag isspecified, it will beturned no matter what itsshape and 
if the -noturn flag isspecified, itwill not beturned no matter what itsshape. 

The - ne or - runlength flag specifies run-length compression. Thismay savetime if the host-to-printer link isslow; but 
normallytheprinter'sprocessingtimedominates, so -ne makesthingsslower. 

The -dpi flag letsyou specify thedots per inch of your output device. The default is300dpi. In theory PostScript isdevice- 
independent and you don't haveto worry about this, but in practi ce its raster rendering can haveunsightly bands if the 
device pixelsand the image pixels aren't in sync. 

The -width and -neignt flags let you specify the sizeof the page. The default i s 8.5 inchesby 11 inches. 

With the -nocenter flag, the output isnotcentered on the page; it appears in the upper-left corner. Thisisuseful for 
programsthat can include PostScript fi les, but can't copewith picturesthat are not positioned in the upper-left corner. The 
default is -center--the image is centered on the page. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEE ALSO 

pnm(5), psidtopgm(l) 

AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. M odified N ovember 1993 by Wolfgang Stuerzli nger (wrzi@gup.uni-iinz.ac.at). 

26 October 1991 
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pnmtorast 

pnmtorast— Convert a portable pixmap into a Sun raster file 
SYNOPSIS 

pnmtorast [ -standard ] -rie] [ p n mf ile] 

D ESC RIFIO N 

pnmtorast reads a portable pixmap as input and producesaSun raster file as output. 

Color values in Sun raster fi les are eight bitswide, so pnmtorast will automatically scale colorsto haveamaxvai of 255. An 
extra pnmdeptn step is not necessary. 

OPTIONS 

The -standard f lag forcesthe result to be i n rt_standard form; the -rie flag, rt_byte_encoded, which issmaller but, well, less 
standard. The default is - ne. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

rasttopnm(l), pnm(5) 

AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. 

12 January 1991 

pnmtosgi 

pnmtosgi— Convert a portable anymap to an SGI imagefile 
SYNOPSIS 

pnmtosgi [ -verbatimj -rie] [ -imagename Name ] [pnmf ile] 

DESCRIPTION 

pnmtosgi reads a portable anymap as input and producesan SGI image file as output. The SGI imagewill betwo-dimen- 
sional (onechannel) for PBM and PGM input, and three-dimensional (threechannels) for PPM . 

OPTIONS 

-verbatim W rite an uncompressed file 

-ne (default) Writeacompressed (run-length-encoded) file. 

-imagename nane W rite the stri ng name into the imagename field oftheheader. Thename string is limited to 79 characters. If 
no nameisgiven, pnmtosgi writesno name into thisfidd. 

BUGS 

Probably. 

REFERENCES 

SGI i mage fi le format documentati on (draft v0.95) by Paul H aeberli (paui9sgi.com). Available via FTP at sgi.com: graphics/ 

SGIIMAGESPEC. 
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SEEALSO 

pnm(5), sgitopnm(l) 

AUTHOR 

Copyright© 1994 bylngoWilken (lngo.Wilkeneinformatik.uni-oldenburg.de). 

29 January 1994 

pnmtosir 

pnmtosir— Convert a portableanymap into aSolitaireformat 
SYNOPSIS 

pnmtosir [pnmfile] 

D ESC RIFIO N 

pnmtosir reads a portable anymap as i nput and produce a Solitai re i mage recorder format. 

pnmtosir producesan M Gl TYPE 17 filefor PBM and PGM files. Forppm, itwritesan M Gl TYPE 11 file 

SEEALSO 

sirtopnm(l), pnm(5) 

AUTHOR 

Copyright © 1991 by M arvin Landis. 

20 M arch 1991 
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pnmtotiff— Convert a portableanymap into aTIFF file 
SYNOPSIS 

pnmtotiff [ -none! -packbits | -lzwj -g3| -g4] [ -2d] [ -fili] [ -predictor n] 
[ -msb21sb| -lsb2msb] [ -rowsperstrip n] [pnmfile] 

DESCRIPTION 

pnmtotiff reads a portableanymap asinput. ProducesaTIFF fileas output. 
OPTIONS 

By default, pnmtotiff creates aTIFF filewith LZW compression. Thisisyour best bet most of the ti me. H owever, some 
TIFF readerscan't deal with it. Ifyou wantto try another compression scheme or tweak some of the other even more 
obscure output options, there area number of flagsto play with. 

The-none, -packbits, -ìzw, -g3,and-g4 options are used to overri de the default and set the compression schemeusedin 
creati ng the output file. TheCCITT Group 3 and Group 4 compression algorithmscan only beused with bilevel data. The 
-2d and -fili options are meaningful only with Group 3 compression: -2d requeststwo-dimensional encoding, while -fili 
requeststhat each encoded scanli ne be zero-fi lied to a byte boundary. The - predictor option isonly meaningful with LZW 
compression: a predictor value of 2 causeseach scanli ne of the output i magete undergo horizontal differencing beforeit is 
encoded; a value of 1 forceseach scanli ne to be encoded without differencing. By default, pnmtotiff creates aTIFF filewith 
msb-to-isb fili order. The -msb2isb and -isb2msb options are used to override the default and set the fili order used in 
creati ng the fi le. The - rowsperstrip option can beused to set the number of rows (scanli nes) in each strip of data in the 
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output file. By default, the output file has the number of rows per strip setto a valuethatwill ensureeach strip is no more 
than eight kilobyteslong. 

BUGS 

This program isnot self-contained. To useityou must fetch theTIFF Software package li sted in theoTHER.sYSTEMs fi le and 
configure pbmplus to useiibtiff. SeePBM -PLUS'sM akefilefordetailson this confi guration. 

SEEALSO 

tif f topnm(l), pnm(5) 

AUTHOR 

Derived byjef Poskanzerfrom ras2tiff .c, which isCopyright® 1990 by Sun M icrosystems, Inc. Author: PatrickJ. 

N aughton (naughtonewind.sun.com). 

13 January 1991 

pnmtoxwd 

pnmtoxwd— Convert a portableanymap into an Xll window dump 
SYNOPSIS 

pnmtoxwd [ -pseudodepth n ] [ -directcolor] [pnmf i I e ] 

D ESC RIFIO N 

pnmtoxwd reads a portable anymap as i nput and producesan Xll window dump as output. This window dump can be 
d i spi ayed usi n g th e xwud tool . 

N ormally, pnmtoxwd produces a Stati cGray dump file for PBM and PGM files. For ppm, itwri tesa PseudoColor dump fileif 
there are up to 256 colors in the i nput, and a D i rectC olor dump fi le otherwise. T he -directcolor flag can be used to force a 
D irectColor dump. The -pseudodepth flag can beused to changethedepth of PseudoColor dumpsfrom the default of 8 bits/ 
256 colors. 

SEEALSO 

xwdtopnm(l), pnm(5), xwud(l) 

AUTHOR 

Copyright® 1989, 1991 byjef Poskanzer. 

24 September 1991 

ppm3d 

ppm3d— Convert two portable pixmap into a red/blue3D glassespixmap 
SYNOPSIS 

ppm3d I e f t p p mf i I e rightppmfile [hor i zont al _of f set ] 

D ESC RIFIO N 

ppm3d reads two portable pixmapsas input and produces a portable pixmap as output, with theimagesoverlapping by 
horizontai_offset pixels in blue/red format. 

horizontai_offset defaultsto 30 pixels. Pixmapsmust bethesamesize. 



ppmchange 

SEEALSO 

ppm(5) 

AUTHOR 

Copyright © 1993 by David K. Drum. 

2 N ovember 1993 

ppmbrighten 

ppmbrighten— Changean image'ssaturation and valuefrom an H SV map 
SYNOPSIS 

ppmbrighten [-n] [-s <+- saturation>] [-v <+- value>] <ppmfile> 

D ESC RIPTIO N 

ppmbrighten reads a portable pixmap as input, convertstheimagefrom RGB space to H SV space, and changesthevalueby 
<+- vaiue> as a percentage; thesamewith thesaturation. Use 

ppmbrighten -v 100 

to add 100 percent to the value. 

Then option normalizesthevalueto exist between 0 and 1 (normalized). 
SEEALSO 

pgmnorm(l), ppm(5) 

AUTHOR 

Copyright© 1990 by Brian M offet. Copyright® 1989 byjef Poskanzer. 

Permission to use, copy, modify, and distri butethis software and its documentati on for any purposeand without feeis 
hereby granted, provided that the abo ve copyright noticeappear in ali copiesand that both that copyright noticeand this 
permission noticeappear in supporti ng documentation. This software is provided "as is" without express or implied 
warranty. 

NOTES 

This program does not changethe number of colors. 

20 N ovember 1990 

ppmchange 

ppmchange— Change ali pixelsof one color to another in a portable pixmap 
SYNOPSIS 

ppmchange o I d c o I or newcolor [...] [ppmfile] 

D ESC RIFIO N 

ppmchange reads a portable pixmap as input and changesall pixelsof oi dcoi or to newcoi or, leavingall othersunchanged. Up 
to 256 colors may be replaced by specifyi ng couples of colorson thecommand line 
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Thecolorscan bespecified infiveways: 

■ A name, assumingthat a pointer to an Xll-style color namesfilewascompiled in. 

■ An Xll-style hexadeci mal specifier: rgb:r/g/b, where r, g, and b areeach 1- to 4-digit hexadecimal numbers. 

■ An Xll-style deci mal specifier: rgbi:r/g/b, where r, g, and b are floati ng-poi nt numbers between 0 and 1. 

■ For backwards COmpatibility, an Old-X 11-Style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, Or#rrrrggggbbbb. 

■ For backwards compatibility, atriplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (Thisstylewasadded beforeM IT cameup with the si milar rgbi style.) 

SEEALSO 

pgmtoppm(l), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whbUusc.edu), with modificationsby Alberto Accomazzi (alberto@cfa.harvard.edu). 

3 Decemberl993 

ppmdim 

ppmdim— Dima portable pixmap down to total blackness 
SYNOPSIS 

ppmdim di mf act or [ p p mf i I e ] 

D ESC RIPTIO N 

ppmdim reads a portable pixmap as input and diminishesits brightness by the specified dimfactor down to total blackness. The 
di mf act or may be in therangefrom 0.0 (total blackness, deep night, nada, nuli, nothing) to 1.0 (originai picture's bright- 
ness). 

Aspnmgamma does not do the bri ghtness correction in theway I wanted it, I wrotethissmall program, 
ppmdim issimilarto ppmbrighten, but not exactly the same 

SEEALSO 

ppm(5), ppmflash(l), pnmgamma(l), ppmbrighten(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 

ppmdist 

ppmdist— Simplistic grayscale assignment for machine-generated color images 
SYNOPSIS 

ppmdist [ -intensityl -frequency] [ p p mf ile] 

DESCRIPTION 

ppmdist reads a portable pixmap as i nput and performs a simplistic grayscale assignment i ntended for use with grayscale or 
bitmap printers. 



ppmdither 




Often conversion from ppm to pgm will yield an imagewith contrai too low for good printer output. The program maximizes 
contrai Petween the gray levels' output. 

A ppm input of n colors isread, and a pgm of n gray levels iswritten. The gray levels takeon thevaluesa. . .n-1, whilemaxvai 
takeson n-1. 

Themappingfrom color to stepped grayscalecan Peperformed in order of input pixel intensity, or input pixel frequency 
(numPer of repeti tions). 

OPTIONS 

-frequency Sort input colors Py the numPer of ti mes a color appears in the input, Peforemappingto evenly di stri P- 
uted gray levels of output. 

-intensity Sort input colors by the r grayscale intensity, beforemappingto evenly di stri Puted gray levels of output. 
Thisis the default. 

BUGS 

H elpful onlyfor imageswith a very small numPer of colors. Perhapsshould havePeen an option to ppmtopgm(l). 
SEEALSO 

ppmtopgm(l), ppmhist(l), ppm(5) 

AUTHOR 

Copyright© 1993 Py Dan StromPerg. 

22 July 1992 

ppmdither 

ppmdither— 0 rdered dither for color images 
SYNOPSIS 

ppmdither [ -dim d i me n s i o n ] [ -red shades ] [ -green s h a d e s ] [ -blue shades ] [ppmf i I e ] 

D ESC RIFIO N 

ppmdither reads a portable pixmap as input, and appliesdithering to it to reduce the numPer of colors used down to the 
specified numPer of shades for each primary. The default numPer of shades isred=5, green=9, biue=5, for a total of 225 
colors. To converttheimageto a Pinary RGB format suitaPlefor color printers, use -red 2 -green 2 -blue 2.Themaximum 
numPer of colors thatcan Peused i s 256 and can Pecomputed astheproduct of the numPer of red, green, and Plue shades. 

OPTIONS 

-dim di me n s i o n 
-red shades 
-green shades 
-blue shades 

SEEALSO 

pnmdepth(l), ppmquant(l), ppm(5) 

AUTHOR 

Copyright 19 1991 Py ChristosZoulas. 

14 July 1991 



Thesize of the dithering matrix. M ust Pea power of 2. 
ThenumPerof red shades to Peused; minimum of 2. 
T he numPer of green shades to Peused; minimum of 2. 
ThenumPerof Plue shades to Peused; minimum of 2. 
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ppmflash 

ppmfiash— Brighten a pictureup to complete white-out 
SYNOPSIS 

ppmflash fi ashfactor [ppmfile] 

D ESC RIFIO N 

ppmflash reads a portable pixmap as input and increases its brightness by the specified fi ashfactor up to a total white-out 
image. Thefi ashfactor may bein therangefrom 0.0 (originai picture's brightness) to 1.0 (full white-out, The Second 
After). 

Aspnmgamma does not do the bri ghtness correction in theway I wanted it, I wrotethissmall program. 
This program issimilarto ppmbrighten, but not exactly thesame 

SEEALSO 

ppm(5), ppmdim(l), pnmgamma(l), ppmbrighten(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 



ppmf orge 

ppmf orge— Fractal forgeries of clouds, planets, and starry skies 
SYNOPSIS 

ppmforge [ -clouds] [ -night] [ -dimension dimen][-hour hou r ] [ -inclìnation ] -tilt angle] 
[ -mesh si ze ] [ -power f act or ] [ -glaciers I ève ] [ - ice I ève ] [ -saturation s at ] 
[ -seed s eed ] [ -stars f r a c t i ori ] [ -xsize j -width wi dt h ] [ -ysize | -height h e i g h t ] 



DESCRIPTION 

ppmforge generates three kindsof "random fractal forgeries," theterm coi ned by Richard F. Vossof the IBM Thomas 
J. Watson Research Center for seemingly reali stic picturesof naturai objects generated by simplealgorithmsembodying 
randomnessand fractal self-similarity. Thetechniquesused by ppmforge areessentially thosegiven by Voss, particularly the 
techniqueof spectral synthesisexplained in moredetail by DietmarSaupe. (The"SeeAlso" subsection providesmore 
detailed information aboutthesemen'swork.) 

The program generates two varietiesof pictures, planets and clouds, which arejust different renderingsof data generated in 
an identical manner, illustrati ng the unity of the fractal structureof thesevery different objects. A third typeof picture, a 
starry sky, issynthesized directlyfrom pseudorandom numbers. 

The generation of planets or clouds beginswith the preparati on of an array of random data in thefrequency domain. The 
si ze of th i s array, themesh size, can besetwith the -mesh option; the larger the mesh, the more reali stic the pictures, but the 
cai culation ti me and memory requirement i ncreasesas the squareof themesh size. The fractal dimension, which you can 
specify with the -dimension option, determi nes the roughnessof the terrai n on the planet or the scale of detail in the clouds. 
Asthefractal dimension isincreased, morehigh frequency componentsareadded into therandom mesh. 

After themesh is generated, an inverse two-dimensional Fourier transform is performed upon it. This converts the originai 
random frequency domain data into spatial ampli tudes. You scale the real componentsthat resultfrom the Fourier transform 
into numbers from 0 to 1 associ ated with each pointon themesh. You can further modify thisnumber by applying apower 
law scale to it with the - power option. U nity scale leaves the numbers unmodifi ed; a power scale of 0.5 takesthesquareroot 
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of thenumbers in the mesh, whileapower scale of 3 replacesthenumbers in the mesh with their cubes. Power law scali ng is 
best envisioned by thinking of thedata as representing the elevation of terrain; powerslessthan oneyield landscapeswith 
vertical scarpsthat look likeglacial-carved valleys; powersgreaterthan onemakefairy-castlespires(which require largemesh 
sizes and high resolution for best results). 

After these calculations, you havean array of thespecified size contai ni ng numbersthat rangefrom 0 to 1. Thepixmaps are 
generated asfollows: 

ciouds A color map iscreated that rangesfrom pure blue to whiteby increasi ng admixture(desaturation) of blue with 
white. N umberslessthan 0.5 arecolored blue, and numbers between 0.5 and 1.0 arecolored with corresponding 
levelsof white, with 1.0 being pure white. 

pianet The mesh is projected onto asphere Values lessthan 0.5 aretreated as water and values between 0.5 and 1.0 as 
land. Thewater areas arecolored based on the water depth; land, based on its elevation. Therandom depth data 
areused to create ciouds over the oceans. An atmosphere approximately likethe Earth's is simulateci; itslight 
absorption iscalculated to create a blue cast around thelimb of the pianet. A function that risesfrom 0 to 1 based 
on latitude is modulateci by the locai elevation to generate poi ar icecaps— high altitude terrain carri es giaci ers 
farther from thepole. Based on theposition of the star with respect to theobserver, theapparent color ofeach 
pixel of the pianet iscalculated by ray-tracingfrom the star to the pianet to theobserver and applyinga lighting 
model that sumsambient light and diffuse refi ection (for most planetsambient light iszero, as their primary star 
istheonly sourceof illumination). Additional random data areused to generate stars around the pianet. 

Night A sequenceof pseudorandom numbers isused to generate stars with auser-specified densi ty. 

Cloud picturesalwayscontain 256 orfewercolorsand may bedisplayed on mostcolor-mapped deviceswithoutfurther 
processing. Pianet pictures often contai n tensof thousands of colors that must becompressed with ppmquant or ppmdither 
before encoding in a color-mapped format. If the display resolution is high enough, ppmdither generally produces better- 
looking planets. ppmquant tendsto create discrete color bands, particularly in the oceans, which are unrealistic and distract- 
ing. Thenumber of colors in starry sky pictures generated with the - night option dependson thevaluespecified for 
-saturation. Small values limit the color temperature distri bution of thestarsand reducethenumberof colors in theimage. 
If the -saturation issetto 0, none of the stars will becolored and the resulti ng imagewill never contai n morethan 256 
colors. N ight sky pictures with many different star colors often look best when color-compressed by pnmdeptn rather than 
ppmquant or ppmdither.Try newmaxvai settingsof 63, 31, or 15 with pnmdepth to reduce the number of colors in thepictureto 
256 orfewer. 
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-hour h o u r 



-glaciers I evel 



-dimension di men 



-ciouds 



Generate ciouds. A pixmap offractal ciouds is generated. Selecting ciouds sets the default 
forfractal dimension to 2.15 and power scalefactorto 0.75. 
Sets the fractal dimension to thespecified dimen, which may beany floati ng-poi nt value 
between 0 and 3. H igher fractal dimensions create more "chaotic" images, which require 
higher resolution output and a larger FFT mesh sizeto look good. If no dimension is 
specified, 2.4 isused when generating planets and 2.15 for ciouds. 
The floati ng-point i ève setti ng controlstheextent to which terrain elevation causes iceto 
appear at lower latitudes. T he default value of 0. 75 makes the polar caps extend toward the 
equator acrosshigh terrain and forms giaci ers in the highest mountains, ason Earth. H igher 
values make ice sheets that cover more and more of the land surface, simulating planets in 
the midst of an iceage. Lower values tend to beboring, resulting in unrealistic geometri cai ly 
precise ice cap boundaries. 

When generating a pianet, hour isused as the hour angle at the centrai meridian. If you 
specify -hour 12, forexample, the pianet will befully illuminated, corresponding to high 
noon at the longitudeat the center of thescreen. You can specify any floati ng-point value 
between 0 and 24 for hour, but values which place most of the pianet in darkness(0 to 4 
and 20 to 24) result in crescents which, while pretty, don't giveyou many illuminated pixels 
for theamount of computing that's required. If no -hour option is specified, a random hour 
angle ischosen, biased sothatonly 25 percent of the images generated will be crescents. 
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-ice levei Sets the extent of the polar ice caps to thegiven floating-point ìevei. The default level of 

0.4 producesice capssimilar to tnoseof the Earth. Smaller values reduce the amountof ice 
whilelarger - ice setti ngs create more prominent ice caps. Sufficiently large values, such as 
100 or more, in conjunction with small setti ngs for -giaciers (try 0.1) create "ice balls" like 
Europa. 

-inciination|-tiit angle The inclination angle of the planet with regard to its primary star is set to angle, which can 
beany floating-point vai uefrom -90 to 90. Theinclination anglecan bethought of as 
specifying, in degrees, the"season" the planet ispresently experi encing or, more preci sely, 
the latitudeat which th e star tran si ts th e zen i th at locai noon. If 0, the planet isatequinox; 
the star is directly overhead at theequator. Positive values represent summer in the northern 
hemisphere, negati ve values summer in the southern hemisphere. The Earth 's inclination 
angle, forexample, is about 23.5 atthejunesolstice, 0 attheequinoxesin M arch and 
September, and -23.5 at theDecember solstice. If no inclination angle isspecified, a 
random valuebetween -21.6 and 21.6 degrees ischosen. 

-mesh s i z e Ameshofsize by s i z e wi II be used for thefast Fourier transform (FFT ). N ote that 

memory requirementsand computation speed increaseasthesquareof si ze; if you doublé 
the mesh size, the program will use fourtimes the memory and run fourtimesaslong. The 
default mesh is 256x256, which producesreasonably good looking pictures while usi ng half a 
megabyte for the 256x256 array of single preci si on complex numbers required by the FFT. 
On machineswith limited memory capaci ty, you may haveto reduce the mesh size to avoid 
running out of RAM . I ncreasi ng the mesh size produces better looking pictures; the 
differencebecomes parti cularly noticeablewhen generati ng high-resolution imageswith 
relati vely high fractal dimensions(between 2.2 and 3). 

-night A starry sky isgenerated. Thestarsarecreated by thesamealgorithm used for the stars that 

surround planet pictures, but the output consists exclusively of stars. 

-power f actor Sets the power factor used to scale elevati onssynthesized from the FFT to fa et or , which can 

beany floating-point number greater than zero. If no factor isspecified, a default of 1 .2 is 
used if a planet isbeinggenerated, or 0.75 if clouds areselected by the -ciouds option.The 
result of the FFT imagesynthesis isan array of elevation values between 0 and 1. A 
nonunity power factor exponentiateseach ofthese elevati onsto the specified power. For 
example, a power factor of 2 squareseach value, whi le a power factor of 0.5 replaceseach 
with itssquareroot. (N ote that exponentiating values between 0 and 1 yields values that 
remain within that range.) Power factors less than 1 emphasizelarge-scaleelevation changes 
at the expenseof small variations. Power factors greater than 1 increasetheroughnessof the 
terrain and, likehigh fractal dimensions, may requirealarger FFT mesh size or higher 
screen resolution to look good. 

-saturation sat Controls the degree of color saturation of the stars that surround planet pictures and fili 

starry skiescreated with the - night opti on. The default value of 125 creates stars that 
resemblethesky asseen by the human eyefrom Earth'ssurface. Stars aredim; onlythe 
bri ghtest activate the cones in the human retina, causi ng color to beperceived. H igher 
values of sat approximate the appearanceof stars from Earth orbit, where better dark 
adaptation, absenceof sky glow, and theconcentration of lightfrom agiven star onto a 
smaller area of the retina than ks to thelack of atmospheric turbulence enhancesthe 
perception of color. Values greater than 250 create "sci enee fiction" skies that, while pretty, 
don'toccur in thisuniverse. 

Thanksto theinversesquarelaw combined with nature'sloveof mediocrity, thereare 
many, manydim stars for every bright one. Thispopulation relationship isaccurately 
refi ected in the skiescreated by ppmforge. D im, low mass stars li ve much longer than bright, 
massive stars; consequently thereare many reddish stars for every blue giant. This relation- 
ship ispreserved by ppmforge. You can reverse the proportion, simulati ng the sky asseen in a 
starburst galaxy, by specifying a negative sat value. 
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-seed num Setstheseed fortherandom numbergeneratortotheintegernum.Theseed usedto create 

each picture is displayed on standard output (unless suppressed with the -quiet option). 
Picturesgenerated with the same seed will be identi cai. If no -seed isspecified, a random 
seed derived from the date and ti me will bechosen. Specifyingan explicit seed allowsyou to 
re- render a picture you parti cularly likeata higher resolution or with different viewing 
parameters. 

-stars fraction Specifies the percentage of pixels, intenthsof apercent, thatwill appear as stars, either 

surrounding a planet or filli ng the enti re frameif -night isspecified. The default f racti on is 
100. 

-xsize| -width width Sets the width of the generateci imageto wi dth pixels. The default width is 256 pixels 

I mages must be at least as wide as they are high; if a width less than the height is speci fi ed, it 
will beincreased to equal the height. If you must havea long, skinny pixmap, makeasquare 
onewith ppmforge, then usepnmcut to extract a portion of theshapeand sizeyou require. 

-ysize| -height height Sets the height of the generated imageto he i ght pixels. The default height ÌS256 pixels. If 

the height specified exceeds the width, the width will beincreased to equal the height. 

Ali flagscan be abbrevi ated to their shortest unique prefix. 
BUGS 

T he algori thms require the output pixmap to beat least as wide as it ishigh, and the width to bean even number of pixels. 
Theseconstraintsareenforced by increasing the size of the requested pixmap if necessary. 

You may haveto reduce the FFT mesh sizeon machineswith 16-bit i ntegers and segmented pointer architectures. 
SEEALSO 

pnmcut(l), pnmdepth(l), ppmdither(l), ppmquant(l), ppm(5) 

"Random Fractal Forgeries" by Richard F. Voss, in Fundamental Algorithmsfor Computer Graphicby Earnshaw et al. Berlin: 
Springer-Verlag, 1985. 

T he Science 0 f F ractal Images, edited by H. 0. Peitgen and D. Saupe. New York: Springer-Verlag, 1988. 

AUTHOR 

John Walker 
Autodesk SA 

AvenuedesChamps-M ontants 14b 
CH-2074MARIN 

Sui sse/ Sch wei z/ Svi zzerà/ Svizra/ Swi tzerl an d 

Usenet: kelviniaAutodesk.com 

Fax: 038/33 88 15 
Voice 038/33 76 33 

Permission to use, copy, modify, and distri butethis software and its documentati on for any purposeand without feeis 
hereby granted, without any conditionsor restri ctions. T hi s software isprovided "as is" without express or implied warranty. 

PLUGWARE! If you likethis kind of stuff, you may also enjoyJamesGleickVChaos— The Software" for M S-DOS, 
available for $59.95 from your locai software sto re or d i recti y from Autodesk, Inc., Attn: Science Seri es, 2320 M ari nship 
Way, Sausalito, CA 94965, USA. Tdephone: 800-688-2344 toll-free or, outsidetheU.S. 415-332-2344 Ext 4886. 
Fax: 415-289-4718. "C haos— The Software" i ncludes a more comprehensi ve fractal forgery generato rthatcreates three- 
dimensional landscapesaswell ascloudsand planets, plus five more modulesthatexploreotheraspectsofC haos. The user 
guideof more than 200 pagesi ncludes an introduction byJamesGleick and detailed explanationsby Rudy Rucker of the 
mathematicsand algorithmsused by each program. 

25 October 1991 
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ppmhist 

ppmhist— Print a histogram of a portable pixmap 
SYNOPSIS 

ppmhist [ p p mf ile] 

D ESC RIPTIO N 

ppmhist reads a portable pixmap as input and generates a histogram of thecolorsin the pixmap. 
SEEALSO 

ppm(5), pgmhist(l) 

AUTHOR 

Copyright® 1989 byjef Poskanzer. 

3 Aprii 1989 

ppmmake 

ppmmake— C reate a pixmap of a specified size and color 
SYNOPSIS 

ppmmake color wi dt h h e i ght 

DESCRIPTION 

ppmmake produces a portable pixmap of the specified color, width, and height. 
Thecolorcan be specified in fiveways: 

■ A name, assumingthat a pointer to an Xll-style color namesfilewascompiled in. 

■ An Xll-style hexadeci mal specifier: rgb:r/g/b, where r, g, and b areeach 1- to 4-digit hexadecimal numbers. 

■ An Xll-style deci mal specifier: rgbi:r/g/b, where r, g, and b are floati ng-poi nt numbers between 0 and 1. 

■ For backwards COmpatibility, an Old-X 11-Style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, Or#rrrrggggbbbb. 

■ For backwards compatibility, atriplet of numbers separated by commas: r,g,b, where r, g, and b are floati ng-poi nt 
numbers between 0 and 1. (Thisstylewasadded beforeM IT cameupwith thesimilar rgbi style.) 

SEEALSO 

ppm(5), pbmmake(l) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

24 September 1991 

ppmmix 

ppmmix— Blend togethertwo portable pixmaps 
SYNOPSIS 

ppmmix f a def a et or ppmfilel p p mf i I e 2 



ppmntsc 



D ESC RIFIO N 

ppmmix readstwo portablepixmapsas input and mixesthem together usi ng the speci fi ed fadefactor. Thefadefactor may be 
in therangefrom 0.0 (only p p mf i i ei's imagedata) to 1.0 (only ppmf i i e2's imagedata). Anything in between gainsasmooth 
blend between thetwo images. 

Thetwo pixmapsmust havethesamesize. 
SEEALSO 

ppm(5) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 

ppmnorm 

ppmnorm— N ormalizethecontrast in a portable pixmap 
SYNOPSIS 

ppmnorm[ -bpercent N ] -bvalue N][-wpercent N ] -wvalue N ] [ppmf i I e ] 

DESCRIPTION 

ppmnorm reads a portable pixmap as input; normalizesthecontrast by forcing the lightest pixelsto white, thedarkest pixelsto 
black, and li nearly rescaling the ones in between; and produces a portable pixmap as output. 

It works by computing the relative gray leve! of each pixel aswith ppmtopgm, and usesthosevaluesto scale the RGB levels. 
N otethat thisisdifferentfrom using pgmnorm on the individuai red, green, and bluegraymaps(asproduced by ppmtorgb3) 
and recombiningthem. 

0PTI0NS 

By default, thedarkest two percent of ali pixelsaremapped to black, and the lightest onepercent aremapped to white. You 
can overridethesepercentagesby using the -bpercent and -wpercent flags, or you can specify the exact pixel valuesto be 
mapped by using the -bvalue and -wvalue flags. Appropriate numbersfortheflags can begotten from theppmhist tool. If 
you just wantto enhancethecontrast, then choosevaluesatelbowsin thehistogram; forexample, if value 29 represents3 
percent of the imagebut value 30 represents20 percent, choose30 for bvalue. If you wantto lighten theimage, then set 
bvaiue to 0 and just f iddi e with wvalue; similarly, to darken theimage, setwvaiue to maxvai and play with bvalue. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

pgmnorm(l), ppmhist(l), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb@usc.edu), heavily based on the pgmnorm fi Iter byjef Poskanzer. 

7 October 1993 

ppmntsc 

ppmntsc— M ake a portable pixmap look likeit istaken from an American TV show 
SYNOPSIS 

ppmntsc di mf a et or [ppmf i I e ] 
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D ESC RIFIO N 

ppmntsc readsa portable pixmap as input and dimsevery other row of imagedata down by the specified dim faeton This 
factor may bein therangeof 0.0 (the alternate lines are total ly black) to 1.0 (originai image). 

Thiscreatesan effect similarto what I saw once in the video clip "You Could beM ine" by Guns'n' Roses. In the scene l'm 
talkingaboutyou can seejohn Connoron hismotorbike, looking up from the water trench (?) he's standing in. Whilethe 
camera pulls back, the image becomes"normal" by brightening up the alternate rowsofit. I thoughtthiswould bean 
i nteresting effect totry in M PEG. I did not yet check this out, however. Tryforyourself. 

SEEALSO 

ppm(5), ppmdim(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 

ppmpat 

ppmpat— M akea pretty pixmap 
SYNOPSIS 

ppmpat -gingham2| -g2 -gingham3 -g3 -madrasj -tartan! -poles| -squig! -camo| 
-anticamo wi dt h h e i g h t 

DESCRIPTION 

ppmpat produces a portable pixmap of the speci fi ed width and height, with a pattern in it. 

Thisprogram ismainlyto demonstrateuseof theppmdraw routines, asimplebut powerful drawing library. Seetheppmdraw.n 
includefilefor moreinformation on usingthese routines. Stili, some of the patterns can berather pretty. If you haveacolor 
workstation, something like ppmpat -squig 300 300 | "ppmquant 128- should generatea nice background. 

0PTI0NS 

Thedifferent flags specify various different pattern types: 



gingham2 


A gingham check pattern. Can betiled. 


gingham3 


A slightly morecomplicated gingham. Can betiled. 


madras 


A madras plaid. Can betiled. 


tartan 


A tartan plaid. Can betiled. 


poles 


Color gradients centered on randomly placed poles. M ay need to be run through ppmquant. 


squig 


Squiggly tubular pattern. Can betiled. M ay need to berun through ppmquant. 


camo 


C amouflage pattern. M ay need to be run through ppmquant. 


anticamo 


Anticamouflage pattern; like -camo, but ultra-bright colors. M ay need to be run through ppmquant. 



Ali flags can be abbrevi ated to their shortest unique prefix. 
REFERENCES 

Some of the patterns are from "Designer'sGuideto Color 3" byjeanne Alien. 
SEEALSO 

pnmtile(l), ppmquant(l), ppm(5) 



ppmquant 



AUTHOR 

Copyright© 1989 byjef Poskanzer. 

4 September 1989 



ppmquant 

ppmquant— Quantize the colors in aportablepixmap down to a speci fi ed number 
SYNOPSIS 

ppmquant [ -f loyd | -f s] ncolors [ppmfile] 
ppmquant [ -f loydj -f s] -map ma p f i I e [ppmfile] 

D ESC RIFIO N 

ppmquant reads a portable pixmap as input. It choosesncoiors colors to best represent theimage, maps the existing colors to 
the new ones, and writes a portable pixmap as output. 

Thequantization method isH eckbertVmedian cut." 

Alternatela you can skip the color-choosing step by specifyingyour own set of colors with the-map flag. Themapfiie is just 
appm file; it can beany shape, ali that matters is the colors in it. For instance, to quantize down to the 8-color IBM TTL 
color set, you mightusethefollowing: 

P3 
8 1 
255 

000 

255 0 0 
0 255 0 
0 0 255 
255 255 0 
255 0 255 
0 255 255 
255 255 255 

If you want to quantize one pixmap to use the colors in another one, just usethesecond oneasthemapfile. You don't have 
to reduce it down to only one pixel of each color, just use it as is 

The -fioya7-fs flag enables a Floyd-Steinberg errar diffusi on step. Floyd-Steinberg gives vastly better resultson images 
wheretheunmodified quantization has bandi ng or other artifacts, especially when goingto asmall number of colors such as 
the preceding IBM set. H owever, it doestake substanti al ly more CPU time, so the default isoff. 

Ali flagscan be abbrevi ated to their shortest unique prefix. 
REFERENCES 

"Color Image Quantization for Frame Buffer D i splay," by Paul H eckbert, siggraph '82 Proceedings, page 297. 
SEEALSO 

ppmquantall(l), pnmdepth(l), ppmdither(l), ppm(5) 

AUTHOR 

Copyright® 1989, 1991 byjef Poskanzer. 

12 January 1991 
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ppmquantall 

ppmquantaii— Run ppmquant on abunch of filesall at once, so they share a common colormap 
SYNOPSIS 

ppmquantall ncolors ppmfile ... 

D ESC RIFIO N 

ppmquantall takesa bunch of portablepixmap as input. It choosesncoi ors colorsto best represent ali of theimages, mapsthe 
existing colorsto thenew ones, and overwrites the input fileswith thenew quantized versions. 

Verbose explanation: Sayyou haveadozen pixmapsthatyou wantto display on thescreen ali atthesametime. Yourscreen 
can only display 256 different colors, but thepixmaps haveatotal of athousand or so different colors. Fora single pixmap, 
you solve this problem with ppmquant; thisscript solves it for multiple pixmaps. Ali it does is concatenate them together into 
one big pixmap, run ppmquant onthat, andthen split itup into little pixmaps again. 

(N otethat another way to solve this problem isto preselect a set of colors and then useppmquant's -map option to separately 
quanti ze each pixmap to that set.) 

SEEALSO 

ppmquant(l), ppm(5) 

BUGS 

It'sa csn script, csn seri pts are not portableto System V. Scripts in general arenot portableto non-U N IX environments. 

AUTHOR 

Copyright® 1991 byjef Poskanzer. 

27 July 1990 

ppmqvga 

ppmqvga— 8- piane quanti zation 
SYNOPSIS 

ppmqvga [ options ] [ input file ] 

DESCRIPTION 

ppmqvga quantizesPPM fi lesto eight planes, with optional Floyd-Steinberg dithering. Input isa PPM filefrom thefile 
named, or standard input if no file is provi ded. 

OPTIONS 

-d ditner Apply F I oyd-Stei n berg dithering to thedata 

-q quiet Producesno progress reporti ng, and no terminal output unlessan errar occurs. 

■v verbose P roduces addi ti onal output describi ng the number of colors found, and some informati on on the resulti ng 
mapping. M ay berepeated to generate loadsof internai table output, but generally only useful once. 

EXAMPLES 

ppmqvga -d my_image.ppm ] ppmtogif >my_image.gif 
tgatoppm zombie. tga ] ppmqvga ] ppmtotif > zombie.tif 



ppmshift 

SEEALSO 

ppmquant 

DIAGNOSTICS 

Errar messages if problems; various levelsof optional progress reporti ng. 
AUTHORS 

Originai by LyleRains (irains@netcom.com) asppmq256 and ppmq256fs combined; documented and enhanced by Bill Davidsen 

(davidsengcrd.ge.com). 

COPYRIGHT 

Copyright© 1991, 1992 by Bill Davidsen, ali rights reserved. The program and documentation may befreely distri buted by 
anyone i n source or binary format. Please clearly note any changes. 

Locai 

ppmrelief 

ppmreiief— Run a Laplacian rei ief fi Iter on a portable pixmap 
SYNOPSIS 

ppmrelief [ p p mf il e ] 

DESCRIPTION 

ppmrelief reads a portable pixmap as input, does a Laplacian rei ief fi Iter, and writes a portable pixmap as output. 
The Laplacian rei ief fi Iter isdescribed in Beyond Photography by H olzmann, equation 3.19. It'sasortof edge-detection. 

SEEALSO 

pgmbentley(l), pgmoil(l), ppm(5) 

AUTHOR 

Copyright® 1990 by Wilson Bent (whbehoh-2.att.com). 

11 January 1991 

ppmshift 

ppmshift— Shift linesof a portable pixmap left or right by a random amount 
SYNOPSIS 

ppmshift shift [ p p mf il e ] 

DESCRIPTION 

ppmshift reads a portable pixmap as input and shiftsevery row of image datato the left or right by acertain amount. The 
shift parameter determi nesby how many pixelsa row isto beshifted at most. 

Another oneof thoseeffects I intendedto useforMPEG tests. U nfortunately, this program will not help me nere— it creates 
patternsthat aretoo random to beused for animati ons. Stili, it might giveinteresting resultson stili images. 
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EXAMPLE 

C heck this out: Save your favorite model 's picture f rom somethi ng li ke alt . binaries . pictures . supermodeis (okay, or f rom 
any other picture source), convert it to ppm, and processit li ke this, assumi ng the pi ctureis 800x600 pixel s: 

1. Take the upper half and leave it like it is: pnmcut 0 0 800 300 cs.ppm >upper.ppm. 

2. Takethelower half, flip itupsidedown, dim it, and distort it a little: pnmcut 0 300 800 300 cs.ppm j pnmtiip -tb | 

ppmdim 0.7 | ppmshift 10 >lower.ppm. 

3. C Oncatenate the tWO pieces: pnmcat -tb upper. ppm lower.ppm >newpic . ppm. 

The resulti ng picture looks like the image being refi ected on a water surfacewith slight ripples. 
SEEALSO 

ppm(5), pnmcut(l), pnmflip(l), ppmdim(l), pnmcat(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 

ppmspread 

ppmspread— D isplace a portable pixmap's pixds by a random amount 
SYNOPSIS 

ppmspread amount [ppmfile] 

DESCRIPTION 

ppmspread reads a portable pixmap as input and movesevery pixel around a bit relative to its originai position. amount 
determines by how many pixelsa pixel isto bemoved around at most. 

Pictures processed with this fi Iter wi II seem to besomewhat dissolved or unfocussed (although they appear more coarse than 
images processed by something likepnmconvoi). 

SEEALSO 

ppm(5), pnmconvol(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 

ppmtoacad 

ppmtoacad— C onvert portable pixmap to AutoCAD database or slide 
SYNOPSIS 

ppmtoacad [ -dxb] [ -poly] [ -background col our ] [ -white] [ -aspect rati o][-8][ppmfi I e] 

DESCRIPTION 

ppmtoacad reads a portable pixmap as input. Produces an AutoCAD sii de fi le or binary database import (DXB) file as output. 
If no ppmfìie isspecified, input isread from standard input. 



ppmtoacad 



OPTIONS 

-dxb 



-poly 



-background color 



-white 



-aspect ratio 



An AutoCAD binary database import (DXB) file iswritten. This file is read with theDXBiN 
command and, onceloaded, becomespartoftheAutoCAD geometrical database and can be 
viewed and edited likeany other object. Each sequenceof identical pixels becomes a separate object 
in thedatabase; thiscan result in very largeAutoCAD drawing files. H owever, if you wantto trace 
over a bitmap, it letsyou zoom and pan around thebitmap asyou wish. 
If the -dxb option isnotspecified, theoutputof ppmtoacad isan AutoCAD si i de fi I e. N ormally, 
each row of pixels isrepresented by an AutoCAD lineentity. If -poiy isselected, the pixels are 
rendered as fi lied polygons. If the slide is viewed on a display with higher resolution than thesource 
pixmap, thiswill cause the pixel sto expand instead of appearing as discrete lines against the screen 
background color. Regrettably, this represen tati on yields slide fi lesthat occupy more disc space and 
takelongerto display. 

MostAutoCAD display drivers can beconfigured to useany available color as the screen back- 
ground. Someusersprefer a black screen background, others white, whilesplinter groups advocate 
burnt ocher, tawny puce, and shocking gray. D i scardi ng pixels whoseclosest AutoCAD color 
represen tati on isequal to the background color can substanti al ly reduce the sizeof the AutoCAD 
database or slidefile needed to represent a bitmap. If no -background color isspecified, the screen 
background color isassumed to be black. Any AutoCAD color number may be specified asthe 
screen background; color numbersareassumed to specify the hues defined in the standard 
AutoCAD 256-color palette. 

Becausemany AutoCAD userschoose a white screen background, thisoption isprovided asa 
short-cut. Specifying -white is identical in effectto -background 7. 

If thesource pixmap had nonsquare pixels, the ratio of the pixel width to pixel height should be 
specified as ratio. The resulti ng slide or DXB fi le wi II becorrected so that pixels on the AutoCAD 
screen will besquare. Forexample, to correctan imagemadefor a 320x200 VGA/M CGA screen, 

specify -aspect (3.8333. 

Restricts the colors in the output file to the eight RGB shades. 



Ali flags can be abbrevi ated to their shortest unique prefix. 
BUGS 

AutoCAD hasafixed palette of 256 colors, distri buted alongthehue, lightness, and saturation axes. Pixmaps that contai n 
many nearly identical colors, or colors not closely approximated by AutoCAD 's palette, may bepoorly rendered. 

ppmtoacad works best if the system displaying its output supports the full 256 color AutoCAD palette. M onochrome, 
8-color, and 16-color configurationswill produce less than optimal results. 

When creati ng a DXB fi le or a sii de fi le with the -poiy option, ppmtoacad findsboth vertical and horizontal runsof identical 
pixels and consolidatesthem into rectangular regionsto reduce the sizeof the output file This iseffectivefor imageswith 
largeareasof Constant color, but it'sno substitutefor trueraster to vector conversi on. In particular, thin diagonal lines are 
not opti m ized at ali by this process. 

Output files can behuge. 
SEEALSO 

AutoCAD ReferenceM anual: "Slide File Format" and "Binary Drawing Interchange(DXB) Files"; ppm(5) 

AUTHOR 

John Walker 
Autodesk SA 

AvenuedesChamps-M ontants 14b 
CH-2074 MARIN 

Sui sse/ Sch wei z/ Svi zzerà/ Svizra/ Swi tzerl an d 
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Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 
Voice 038/33 76 33 

Permission to use, copy, modify, and distri butethis software and its documentati on for any purposeand without feeis 
hereby granted, without any conditionsor restri ctions. T hi s software isprovided "asis" without express or implied warranty. 

AutoCAD and Autodesk are regi stered trademarksof Autodesk, Inc. 

10 October 1991 

ppmtobmp 

ppmtobmp— Convert a portablepixmap into a BM P file 
SYNOPSIS 

ppmtobmp [-wi ndows][-os2][ppmfi le] 

D ESC RIFIO N 

ppmtobmp readsaportablepixmapasinput and producesaM icrosoft Windows or OS/2 BM P fileas output. 
OPTIONS 

-Windows Tel Is the program to produce a M icrosoft W indows BM P file 

-os2 Tel Is the program to produce an OS/2 BM P file. (T his is the default.) 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

bmptoppm(l), ppm(5) 

AUTHOR 

C opyright© 1992 by D avid W . Sanderson. 

26 October 1992 

ppmtogif 

ppmtogif — C onvert a portable pixmap i nto a G I F fi le 
SYNOPSIS 

ppmtogif [ -interlace] [ -sort] [ -map ma pf i I e ] [ -transparent col or ] [ppmf il e ] 

D ESC RIFIO N 

ppmtogif readsaportablepixmapasinput and producesaGIF fileas output. 
OPTIONS 

-interiace Tells the program to produce an interlaced GIF file, 

-sort ProducesaGIF filewith asorted colormap. 

-map ma pf i e U ses the colors found in the ma pf i i e to createthecolormap in the G I F file, instead of thecolors 

from ppmf ile. The ma pf m e can beany ppmfile; ali that matters isthe colors in it. If thecolors in 



ppmtoicr 



ppmf ile do not match those in mapf ile, the/ are matched to a "best match." A (much) better result 
can beobtained by usi ng the followi ng fi Iter in advance: 

ppmquant -floyd -map mapfile 

-transparent color Markthegiven color astransparent in the G I F file. Thecolor isspecified asin ppmmake(l). Note 
that thisoption outputs a GIF89a format file, which might not beunderstood by your software. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

giftoppm(l), ppmquant(l), ppm(5) 

AUTHOR 

Based on gifencod by David Rowley (mgardigwatdcsu.waterioo.edu). Lempd-Zivcompression based on compress. 
Copyright© 1989 byjef Poskanzer. 

30 junel993 

ppmtoicr 

ppmtoicr— C onvert a portable pixmap i nto N C SA I C R format 
SYNOPSIS 

ppmtoicr [ -windowname name ] [ -expand e x p a n d ] [ -display di spi ay ] [ -rie] [ppmf i I e ] 

D ESC RIFIO N 

ppmtoicr reads a portable pixmap file as input and produces an N CSA Telnet I nteracti ve C olor Raster graphic file as output. 
Ifppmtiie is not supplied, ppmtoicr will read from standard input. 

Interactive Color Raster (ICR) is a protocol fordisplaying raster graphics on workstation screens. The protocol isimple- 
mented in N CSA Telnet for the M acintosh version 2.3. The ICR protocol sh ares eh aracteri sti cs of the Tektronix graphics 
terminal emulation protocol. For example, escape sequences are used to control the display. 

ppmtoicr will output the appropriate sequences to create a window of the di mensionsof the input pixmap, create a colormap 
of up to 256 colorson the display, then load the picture data into the window. 

Notethatthereisno icrtoppm tool; thistransformation isone-way. 
OPTIONS 

-windownamename Output will bedisplayed in nane . (D efault isto useppm-fiie or "untitled" if standard input isread.) 
-expandexpand Output wi II beexpanded on display byfactor expand. (For example, a valueof 2 will cause four pixelsto be 

displayed for every input pixel.) 
-dispiaydi spi ay Output wi II bedisplayed on screen numbered di spi ay . 

-rie Userun-length encoded format for display. (Thiswill nearlyalways result in a quicker display, butmay 

skew the colormap.) 

EXAMPLES 

T h i s d i spi ays a ppm f i I e usi n g th e protocol : 

ppmtoicr ppmfile 

Thiswill create a window named ppmf ile on the display with thecorrect dimensionsfor ppmf ne, create and download a 
colormap of up to 256 colors, and download the picture into the window. Thesameeffect may beachieved by the followi ng 
sequence: 
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ppmtoicr ppmfile > filename 
cat filename 

To display a GIF fi le usi ng the protocol in awindow titled after the input file, zoom thedisplayed imageby afactor of 2, 
and run-length encode the data: 

giftoppm giffile j ppmtoicr -w giffile -r -e 2 

BUGS 

The protocol usesfrequentffiusn Calisto speed up display. If theoutput issaved to afilefor later display via cat, drawing 
will bemuch slower. In either case, increasi ng the Blocksize limit on the display wi II speed up transmission substantially. 

SEEALSO 

ppm(5) 

N CSA Telnet for theM acintosh, U ni versity of Illinois at U rbana-Champaign (1989) 
AUTHOR 

Copyright© 1990 by Kanthan Pillay (svpiiiay@Princeton.EDu), Princeton U niversity Computing and Information Technol- 
ogy 

30 July 1990 

ppmtoilbm 

ppmtoiibm— Convert a portablepixmap into an ILBM file 
SYNOPSIS 

ppmtoilbm [ -maxplanes | -mp N ] [ -f ixplanes ] -f p N ] [ -ham6 1 -ham8] [ -dcbits -dcplanesrgb] 
[ -normal ] -hamif ] -hamf orce | -24if ] -24f orce ] -dcif ] -deforce | -cmaponly] [ -ecs | -aga] 
[- compress! -nocompress] [ -cmethod t ype ] [ -mapppmfile] [ -savemem] [ppmfile] 

D ESC RIFIO N 

ppmtoilbm reads a portable pixmap as input and producesan ILBM fileas output. Supported ILBM typesarethefollowing: 
N ormai ILBM swith 1-16 planes 
Amiga HAM with 3-16 planes 
24-bit 

Colormap (bmhd and cmap chunk only, nPianes = 0) 

Unofficial direct color 1-16 planesforeach color component 

Chunkswritten: bmhd, cmap, camg (only for HAM ), body (not for colormap files) unofficial dcol chunk for direct color ILBM 
OPTIONS 

Optionsmarked with (*) can beprefixed with no, for example, -nohamif. Ali optionscan beabbreviated to theirshortest 
unique prefix. 

-maxplanes | - mp n (default 5, minimum 1, maximum 16) M aximum planesto write in a normal ILBM . If the 

pixmap doesnotfit into n planes, ppmtoilbm writes a HAM file(if -hamif isused), a 24-bit 
file(if -24if isused), a di rect color fi le (if -dcif isused). orabortswith an errar. 

-fixpianes j -fp n (min 1, max 16) If a normal I LBM iswritten, it will haveexaetlyn planes. 

-nambits | -hampianes n (default 6, min 3, max 16) Select number of planesfor H AM picture. T hecurrent Amiga 
hardware supports 6 and 8 planes, so for now you should only use thisvalues. 



ppmtomap 

-normal (default) 

■hamif (*), -24if (*), 
■dcif (*) 

-hamforce (*), -24force (*), 
-deforce (*) 

-debits | -dcplanes r g b 

-ecs (default) 

-aga 
-ham6 
-ham8 

-compress (*) (default), 
-cmethod none ] byteruM 

-map p p mf ì I e 

-cmaponly 
-savemem 

BUGS 

HAM pictureswill alwaysgetagrayscalecolormap; areal color selection algorithm might give better results. On theother 
hand, thisallows row-by-row operation on HAM images, and ali HAM imagesof thesamedepth (numberof planes) sharea 
common colormap, which isuseful for building HAM animations. 

REFERENCES 

Amiga ROM Kernel ReferenceM anual- Devices (Third Edition), Addison Wesley, ISBN 0-201-56775-X 
SEEALSO 

ppm(5), ilbmtoppm(l) 

AUTHORS 

Copyright© 1989 byjef Poskanzer; modified October 1993 by Ingo Wilken (mgo.wiikenMnformatik.uni-oidenburg.de). 

31 October 1993 

ppmtomap 

ppmtomap— E xtract ali colorsfrom a portablepixmap 
SYNOPSIS 

ppmtomap [ -sort] [ -square] [ p p mf i I e ] 

D ESC RIFIO N 

ppmtomap reads a portable pixmap as i nput and produces a portable pixmap as output, representi ng a colormap of the i nput 
file. Ali n different colorsfound areput in an NX1 portablepixmap. This colormap file can beused asa mapfileforppmquant 

Or ppmtogif . 



Tums Off -hamif / -24if / -dcif, -hamforce/ -24force/ -deforce and -cmaponly. AlSO SetS 

compression typeto byterum. 

W rite a H AM /24-bit/direct color fi le if the pixmap does not fit into maxpianes planes. 
W rite a H AM /24-bit/direct color file. 

(default 5, min 1, max 16). Select number of bitsforred, green, and blue in a direct color 
ILBM. 

ShortCUtfor: -hamplanes 6 -maxplanes 5 
ShortCUtfor: -hamplanes 8 -maxplanes 8 
ShortCUt for: -hamplanes 6 -hamforce 
ShortCUtfor: -hamplanes 8 -hamforce 

Compress the body chunk. The default compression method isbyterum. Compression 
requires building thelLBM imagein memory; turning compression off allowsstream- 
writing of theimage, but the resulti ng file wi II usually be30 percent to 50 percent larger. 
Another alternative isthe -savemem option; thiswill keep memory requirementsfor 
compression at a minimum, but isvery slow. 

Writeanormal ILBM using the colors in ppmfi i e asthecolormap.Thecolormapfilealso 
determines the numberof planes; a -maxplanes or -fixpianes option isignored. 
W rite a colormap file: only bmhd and cmap chunks, no body chunk, nPianes = 0. 
Seethe -compress Option. 
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OPTIONS 

■sort Producesaportablepixmapwith thecolorsin somesorted order 

-square Produces a (more or less) square output fi le instead of putting ali colorson the top row 

Ali flagscan be abbrevi ated to their shortest unique prefix. 
WARNING 

If you want to use the output fileasa mapfilefor ppmtogif, you first haveto do a ppmquant 256 because ppmtomap isnot 
li mited to 256 colors (butto 65536). 

SEEALSO 

ppmtogif(l), ppmquant(l), ppm(5) 

AUTHOR 

M arcel W ijkstra (wijkstt-aufwi.uva.nl) 
Copyright© 1989 byjef Poskanzer. 

11 Auguà 1993 



ppmtomitsu 

ppmtomitsu— Convert a portablepixmap to a M itsubishi S340-10 file 
SYNOPSIS 

ppmtomitsu [ -sharpness «al ] [ -enlarge vai ][ -media st r I ng ] [ -copy vai ] 
[ -dpi300] [ -tiny] [p p mf I I e ] 

D ESC RIFIO N 

ppmtomitsu reads a portablepixmap as input and converts it into a format suitableto beprinted by aM itsubishi S340-10 
printer, orany other M itsubishi color subii mation printer. 

TheM itsubishi S340-10 Color Subii mation printer supports 24-bit color. Imagesof the avai lable sizes take so long to 
transfer that there i s a fast method, employing a lookup tablethat ppmtomitsu will use if thereis a maximum of 256 colors in 
thepixmap. ppmtomitsu will try to position your i magete the center of thepaper, and will rotate your imagefor you if xsize 
is larger than ysize. If your imageis larger than the media allows, ppmtomitsu will quit with an error message (Wedecided 
that the media weretoo expensiveto have carelessusers produce misprints.) After data transmission has started, the job can't 
bestopped in asaneway without resetting the printer. The printer understands putting together imagesin theprinter's 
memory; ppmtomitsu doesn't utilize this as pnmcat and so on provi de the samefunctionality and letyou viewtheresult 
onscreen, too. TheS340-10 isthe lowest common denomi nator printer; for higher resolution printers, there'sthedpi300 
option.Theotherprintersalsosupporthighervaluesfor eniarge eg, butl don'tthink that's essenti al enough to warrant a 
change in the program. 

-sharpness 1-4 Sharpness designation. D efault is to use the current sharpness. 

-eniarge 1-3 Enlarge by afactor; default is 1 (no enlarge) 

-media a, A4, as, A4S D esignate the media you're using. D efault is 1 1 84 x 1350, which will fiton any media. A is 1216 x 
1350, A4 is 11 84 x 1452, AS is 1216 x 1650, and A4S ÌS1184 x 1754. A warning: If you specify a 
different media than the printer currently has, the printer will wait until you put in thecorrect 
media orswitch i t off. 

-copy 1-9 Thenumberof copiesto produce. Default isi. 

-dpi30B Doublé the number of allowed pixels for a S3600-30 Printer in S340-10 compati bility mode. (The 

S3600-30 has300dpi.) 



ppmtopgm 

-tiny M emory-safing, but alwaysslow. T he pri nter wi II get the data line-by-line in 24-bit. It's probably a 

good ideato usethisif your machine starts paging a lot without thisoption. 

REFERENCES 

M itsubishi Sublimation Full Color Printer 5340-10; Speci fi cationsof Parai lei Interface LSP-F0232F 
SEEALSO 

ppmquant(l), pnmscale(l), ppm(5) 

BUGS 

Wedidn't find any— yet. Besides, they're called featuresanyway :-) If you should find one, please e-mail meatthefollowing 
address. 

AUTHOR 

Copyright© 1992, 1993 by S. Petra Zeidler, M PIFR Bonn, Germany (spzuspeckiec.mpifr-bonn.mpg.de). 

29 January 1992 

ppmtopcx 

ppmtopcx— C onvert a portable pixmap i nto a PC X fi le 
SYNOPSIS 

ppmtopcx [ p p mf ile] 

D ESC RIFIO N 

ppmtopcx reads a portable pixmap as input and producesaPCX fileas output. 
SEEALSO 

pcxtoppm(l), ppm(5) 

AUTHOR 

C opyright © 1990 by M ichael D avidson. 

9 Aprii 1990 

ppmtopgm 

ppmtopgm— C onvert a portable pixmap i nto a portable graymap 
SYNOPSIS 

ppmtopgm [ p p mf i I e] 

D ESC RIFIO N 

ppmtopgm reads a portable pixmap as input and produces a portable graymap as output. The quantization formula used is 
.299 r +.587 g + .114 b. 

N otethat although thereisapgmtoppm program, it isnot necessary for simpleconversionsfrom pgm to ppm, because any ppm 
program can read pgm (and pbm ) files automagically. pgmtoppm isfor colorizing a pgm file. Also, seeppmtorgb3 for a different 
way of converti ng color to gray. 
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QUOTE 

Cold-hearted orb that rules the night 
Ranovesthecolorsfrom our sight 
Red isgray, and yellow white 
Butwedecidewhich isright 
And which isa quantization errar. 

SEEALSO 

pgmtoppm(l), ppmtorgb3(l), rgb3toppm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

23 Decemberl988 

ppmtopil 

ppmtopn — C onvert a portable pixmap i nto an Atari D egas PI 1 fi le 
SYNOPSIS 

ppmtopil [ p p mf ile] 

D ESC RIFIO N 

ppmtopil reads a portable pixmap as input and produces an Atari D egas PI 1 fi le as output. 
SEEALSO 

piltoppm(l), ppm(5), pbmtopi3(l), pi3topbm(l) 

AUTHOR 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 

19 July 1990 

ppmtopict 

ppmtopict— C onvert a portable pixmap into a M acintosh PICT file 
SYNOPSIS 

ppmtopict [ p p mf i I e ] 

DESCRIPTION 

ppmtopict reads a portabl e pi xmap as i n put and produces a M aci ntosh P I C T f i I e as output. 

Thegenerated fileisonly the data fork of a picture. You wi II need a program such asmcvert to generate a M acbinary or a 
BinH ex fi le that contai ns the necessary information to identify thefileasa PICT fileto M acOS. 

Even though PICT supports2 and 4 bitsper pixel, ppmtopict alwaysgeneratesan 8-bits-per-pixel file. 
BUGS 

T he picture size field isonly correct if the output isto a file becausewriting into thisfield requiresseeking backwardson a 
file. H owever, the PICT documentation seemsto suggest that thisfield isnot criticai anyway becauseit isonly the lower 16 
bitsof the picture size 



ppmtopj 




SEEALSO 

picttoppm(l), ppm(5), mcvert(l) 

AUTHOR 

Copyright® 1990 by Ken Yap (ken@cs.rocester.edu). 

15 Aprii 1990 

ppmtopj 

ppmtopj— Converta portable pixmap to an HP PaintJet file 
SYNOPSIS 

ppmtopj [-gamma vai ][-xpos vai ][-ypos vai ][-back dark ] lite] [- rie] [ -center] 
[ - render none | snap | bwj dither | diffuse | monodither ] monodiffuse | clusterdither ] 
monoclusterdither] [ p p mf i I e ] 

D ESC RIFIO N 

ppmtopj reads a portable pixmap as input and converts it into a format suitableto beprinted by an H P PaintJet printer. 

For best results, theinputfileshould bein 8-color RGB form; that is, it should haveonly theeight binary combinati onsof 
full-on and full-off primaries. You could get this by sending the input file through ppmquant -map with a mapfilesuch as 

P3 
8 1 
255 

0 0 0 2550 0 02550 0 0 255 

255 255 0 255 0 255 0 255 255 255 255 255 

0 r else yOU COUld USe ppmdither -red 2 -green 2 -blue 2. 

OPTIONS 

-rie 
-back 

-render al g 
-gamma i nt 
-center 
-xpos pos 
-ypos pos 

REFERENCES 

H P PaintJ et XL Color GraphicsPrinter User'sGuide 

SEEALSO 

pnmdepth(l), ppmquant(l), ppmdither(l), ppm(5) 

BUGS 

M ostof theoptionshavenot been tested becauseof thepriceof thepaper. 

AUTHOR 

Copyright® 1991 by ChristosZoulas. 

13 July 1991 



Run-length encodetheimage. (Thiscan result in largerimages.) 

Enhancetheforeground by indicati ng if the background is light or dark compared to theforeground. 

Usean internai rendering algori thm (default dither). 

G amma correct the i mage usi ng the integer parameter as a gamma (default 0). 

C enter the i mage to an 8.5 by 11 page 

Movebypos pixels in thex direction. 

Movebypos pixels in they direction. 
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ppmtopjxl 

ppmtopjxl— Convert a portablepixmap into an H P PaintJet XL PC L file 
SYNOPSIS 

ppmtopjxl [-nopack] [-gamma <n> ] [ -presentation] [-dark] [-diffuse] 

[-cluster] [-dither] [-xshift <s> ] [-yshift <s> ] [-xshift <s > ] [-yshift <s > ] 

[ -xsize| -width] -xscale <s> ] [ -ysize j -height ] -yscale <s > ] [ppmfile] 

D ESC RIPTIO N 

ppmtopjxl readsa portable pixmap as input and producesa PCL file suitable for printingon an H P PaintJet XL printer as 
output. 

Thegenerated fileisnot suitable for printingon a normal P ri ntj et printer. The -nopack option generatesafilethatdoesnot 
usethenormal TIFF 4.0 compressi on method. Thisfilemight beprintableon a normal PaintJet printer (not an XL). 

The -gamma option sets the gamma co rrection for theimage. Theuseful range for the Pai ntj et X L isapproximately 0.6 
to 1.5. 

The rendering algori thm used for imagescan bealtered with the -dither, -cluster, and -diffuse options. Theseoptions 
select ordered dithering, clustered ordered dithering, or error diffusi on, respectively. The -dark option can beused to 
enhanceimageswith a dark background when they arereduced in size The -presentation option turnson presentation 
mode, in which two passes are made over the paperto increaseink density. Thisshould beused only for imageswhere 
quali ty i seri ti cai. 

Theimage can be resized by setti ng the -xsize and -ysize options. The parameter to either of theseoptions isinterpreted as 
thenumber of dotsto set the width or height to, but an optional dimension of pt (points), dp (decipoints), in (inches), or cm 
(centimeters) may beappended. If only onedimension isspecified, the other wi II bescaled appropriately. 

Theoptions-widtn and -height are synonymsof -xsize and -ysize. 

The -xscaie and -yscaie opti ons can alternati vely be used to scale the i mage by a si m pie factor. 

The image can be shifted on the page by usi ng the -xshift and -yshift options. T hese move the i mage the specified 
dimensions ri ght and down. 

SEEALSO 

ppm(5) 

AUTHOR 

Angus Duggan 

14 M arch 1991 



ppmtopuzz 

ppmtopuzz— Convert a portablepixmap into an Xll puzzle fi le 
SYNOPSIS 

ppmtopuzz [ppmf il e ] 

DESCRIPTION 

ppmtopuzz readsa portable pixmap as input and producesan Xll puzzle fi le as output. A puzzle fi le is for use with thepuzzie 
program included with theXll distri bution; puzzie's -picture flag letsyou specify an image file. 



ppmtosixel 



SEEALSO 

ppm(5), puzzle(l) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

22 August 1990 

ppmtorgb3 

ppmtorgb3— Separate a portable pixmap i nto three portable graymaps 
SYNOPSIS 

ppmtorgb3 [ p p mf il e ] 

D ESC RIPTIO N 

ppmtorgb3 reads a portable pixmap as input and writes three portable graymaps as output, oneeach for red, green, and blue. 

T he output fi lenames are constructed bytaking the input filmarne, stri pping off any extension, and appending .red, .gm, 
and .blu. For example, separati ngienna.ppm would result in ìenna.red, ìenna.grn, and ìenna.biu. If the input comes from 

stdin, the names are noname. red, noname .grn, and noname. blu. 

SEEALSO 

rgb3toppm(l), ppmtopgm(l), pgmtoppm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright® 1991 byjef Poskanzer. 

10 January 1991 

ppmtosixel 

ppmtosixei— Convert a portable pixmap into DEC sixel format 
SYNOPSIS 

ppmtosixel [ -raw] [ -margin] [ p p mf ì I e ] 

DESCRIPTION 

ppmtosixel readsa portable pixmap as input and produce sixel commands(SIX) as output. The output isformatted for color 
printing, for example, fora D EC LJ250 color inkjet printer. 

If RGB valuesfrom the PPM fi le do not havemaxvai=i00, the RGB valuesarerescaled. A printer control header and a color 
assignment tablebegin theSIX file. Imagedata iswritten in acompressed format by default. A printer control footer ends 
theimage file. 

OPTIONS 

-raw If specified, each pixel will beexplicitly described in theimage file. If -raw isnotspecified, output will default to 
compressed format in which identical adjacent pixels are replaced by repeat pixel commands. A raw fileisoften 
an order of magnitude largerthan acompressed file and prints much slower. 

-margin If -margin is not specified, the i mage wi 1 1 start at theleft margin (of thewindow, paper, or whatever). If -margin is 
specified, a 1.5 inch left margin will offset theimage 
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PRINTING 

Generally, sixel fi les must reach the printer unfiltered. Use the ipr -x option or cat menarne > /dev/ttyo?. 
BUGS 

Upon rescaling, truncation of the least significant bitsof RGB values may result in poor color conversion. If the originai 
PPM maxvai was greater than 100, rescaling also reducestheimagedepth. W hiletheactual RGB values from theppm fi le are 
more or less retai ned, the color palette of the LJ250 may not match thecolorson yourscreen.Thisseemsto bea printer 
limitation. 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright® 1991 by RickVinci. 

26 Aprii 1991 

ppmtotga 

ppmtotga— Convert portablepixmap into aTrueVision Targa file 
SYNOPSIS 

ppmtotga [ -mono! -cmap| -rgb] [ -norie] [ppmf Me] 

DESCRIPTION 

ppmtotga reads a portable pixmap as input and produces a T rueV ision Targa file as output. 
0PTI0NS 

-mono ForcesTarga fileto beof type 8-bit monochrome. Input must bea portable bitmap ora portable graymap. 
-cmap ForcesTarga fileto beof type 24-bit colormapped. Input must bea portable bitmap, a portable graymap, ora 

portable pixmap containing no more than 256 disti net colora 
-rgb ForcesTarga fileto beof type 24-bit unmapped color. 

-norie D isables run-length encoding, in caseyou haveaTarga reader thatcan't read run-length encoded fi les. 

Ali flagscan be abbrevi ated to their shortest unique prefix. If no fi le type is specified, themost highly constai ned compati ble 
type isused, where monochrome is more constai ned than colormapped, which is in turn more constai ned than unmapped. 

BUGS 

Does not supportali possi ble Targa fi le types. Should really beinpnm, notppm. 
SEE ALSO 

tgatoppm(l), ppm(5) 

AUTHOR 

C opyright® 1989, 1991 by M ark Shand and J ef Poskanzer. 

28 October 1991 



ppmtoxpm 



ppmtouil 

ppmtouil— Convert a portable pixmap into a M otif U IL icon file 
SYNOPSIS 

ppmtouil [ - name u il n a me ] [ p p mf il e ] 

D ESC RIPTIO N 

ppmtouil reads a portable pixmap as input and producesa M otif U IL icon file as output. 

If the program wascompiled with an rgb database specified, and an RGB valuefrom theppm input matchesan RGB value 
from the database, then thecorresponding color namemnemonic isprinted in theUlL'scolormap. If no rgb database was 
compiled in, or if the RGB valuesdon't match, then the color will beprinted with the#RGB, #rrggbb, #rrrgggbbb, or 
#rrrrggggbbbb hexadecimal format. 

OPTIONS 

-name Allowsyou to specify the prefix string that isprinted in theresultingU IL output. If not specified, it will default to 
thefilename(without extension) of theppmme argument. If -name is not specified and no ppmfiie is specified 
(that is, piped input), the prefix string will default to the string "noname". 

Ali flags can be abbrevi ated to their shortest unique prefix. 
SEEALSO 

ppm(5) 

AUTHOR 

Converted byjef Poskanzerfrom ppmtoxpm. c, which is copyright® 1990 by M ark W. Snitily. 

31 August 1990 

ppmtoxpm 

ppmtoxpm— Convert a portable pixmap into an Xll pixmap 
SYNOPSIS 

ppmtoxpm [-name <xpmname>] [-rgb <rgb-textfile>] [ <p p mf il e >] 

DESCRIPTION 

ppmtoxpm reads a portable pixmap as input and producesan Xll pixmap (version 3) as output that can beloaded directly by 
theXPM library. 

The - name option allowsyou to specify the prefix string which isprinted in the resulti ngXPM output. If not specified, itwill 
default to thefilename(without extension) of theppmme argument. If -name is not specified and ppmfiie is not specified 
(that is, piped input), the prefix string will default to the string "noname". 

The -rgb option allowsyou to specify an Xll rgb textfileforthelookup of color namemnemonics. ThisRGB textfileis 
typically the /usr/iib/xn/rgb.txt of theM IT Xll distribution, but any fi le usi ng the same format may beused. When 
specified and an RGB valuefrom theppm input matchesan RGB valuefrom the <rgb-textme>, then thecorresponding 
color namemnemonic isprinted in theXPM 'scolormap. If -rgb is not specified, or if the RGB valuesdon't match, then the 
color will beprinted with the#RGB, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb hexadecimal format. 

Ali flags can be abbrevi ated to their shortest unique prefix. 
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Forexample, to convert thefile dot (found in /usr/inciude/xn/bitmaps), from xbm to xpm, you could specify 

xbmtopbm dot ] ppmtoxpm -name dot 

or, with an rgb text f i I e ( i n the locai directory) 

xbmtopbm dot ] ppmtoxpm -name dot -rgb rgb.txt 

BUGS 

An option to match the closest (rather than exact) color name mnemonic from the rgb text would bea desi rableenhance- 
ment. 

Truncation of the least significant bits of an RGB valuemay result in nonexact matcheswhen perforimi ng color name 
mnemonic lookups. 

SEEALSO 

ppm(5) 

XPM M anual byArnaud LeHors(iehors@mirsa. inria.tr). 
AUTHOR 

Copyright © 1990 by M ark W. Snitily. Thistool wasdeveloped for Schlumberger Technologies, ATE D i vision, and with 
thar permission isbeing madeavailableto the public with the above copyright noticeand permission notice. 

U pgraded to XPM 2 by Paul Breslaw, M ecasoft SA, Zurich, Switzerland (pauiiamecazh.uu.ch); Thu, N ov8, 16:01:17, 1990. 

U pgraded to XPM version 3 byArnaud le H ors (iehors@mirsa.inria.fr). 

9 Aprii 1991 

ppmtoyuv 

ppmtoyuv— Convert a portable pixmap into an AbekasYU V file 
SYNOPSIS 

ppmtoyuv [ppmfile] 

D ESC RIFIO N 

ppmtoyuv reads a portable pixmap as input and producesan AbekasYU V fileas output. 
SEEALSO 

yuvtoppm(l), ppm(5) 

AUTHOR 

M are Boucher (<marc@Postimage.coM>), based on ExampleConversion Program, A60/A64 Digital Video Interface M anual, 
page 69. Copyright© 1991 by DH D Post Image Inc. Copyright» 1987 byAbekas Video Systems Inc. 

25 M ardi 1991 

ppmtoyuvsplit 

ppmtoyuvspiit— Convert a portable pixmap into threesubsampled rawYUV files 
SYNOPSIS 

ppmtoyuvsplit ba sena me [ppmfile] 



pr 




D ESC RIFIO N 

ppmtoyuvsplit rfflds a portable pixmap as input and producesthreerawfileS-basename.Y, basename.U, and basename.V— as 

output. Thesefiles are the subsampled raw YUV representati on of the input pixmap, asrequired by the Stanford M PEG 
code. The subsampling isdoneby ari thmetic mean of 4 pixelscolors into one The YUV valuesarescaled accordi ngto 
CC IR. 601, asassumed by M PEG. 

SEEALSO 

mpeg(l), ppm(5) 

AUTHOR 

Copyright© 1993 byAndreBeck (AndreBeckeiRS.Inf.TU-Dresden.de). Based on ppmtoyuv.c. 

9 September 1993 



pr 



pr— C onvert text fi lesfor pri nti ng 
SYNOPSIS 

pr [+PAGE] [-COLUMN] [-abedf Fmrtv] [-e[in-tab-char[in-tab-width] ] ] [-h header] 

[-i[out-tab-char[out-tab-width] ] ] [-1 page-length] [-n[number-separator[digits] ] ] 

[-0 left-margin] [-s[column-separator] ] [-w page-width] [--help] [-- version] [file...] 

D ESC RIFIO N 

Thismanual page documents the GN U version of pr. pr printson the standard output a paginated and optional ly 
multicolumn copy of the text filesgiven on thecommand line, or of the standard input if no filesaregiven orwhen the 
filename- isencountered. Form feeds in the input cause page breaks in the output. 



OPTIONS 

PAGE 
-COLUMN 



-b 
-c 

-d 

-e[in-tab-char 
[in-tab-width] ] 
-F, -f 

-h header 
- -help 

-i[dut-tab-char 
[out-tab-width] ] 

-1 page- 1 engt h 



Begin printing with page page. 

Produce coLUMN-column output and print columnsdown. Thecolumn width isautomatically 
decreased ascoLUMN increases; unlessyou usethe-w option to increase the page width aswdl, this 
option might cause some columnsto betruncated. 
Print columns across rather than down. 
Balance columns on the last page. 

Print control charactersusing hat notation (forexample, "G); print other unprintable characters in 
octal backslash notation. 
Doublé- space the output. 

Expand tabsto spaceson input. Optional argument m-tab-char is the input tab character, default 
tab. Optional argument in-tab-width isthe input tab character'swidth, default 8. 
Useaform feed instead of newlinesto separate output pages. 
Replace thefilename in the header with the stri ng h e a d e r . 
Print ausagemessageand exit with a nonzero status. 

Replacespaceswith tabson output. Optional argument out-tab-char isthe output tab character, 
default tab. Optional argument out-tab-width isthe output tab character'swidth, default 8. 
Set the page length to page- 1 engt h li nes. The default is 66. If page- 1 engt h islessthan 10, the 
headersand footersareomitted, asif the-t option had been given. 
Print ali filesin parai lei, one in each column. 
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Precede each column with a linenumber; with parallel files, precede each line with a linenumber. 
Optional argument number-separator isthecharacterto p ri nt after each number, default tab. 
Optional argument digits is the number of digits perline number, default 5. 
Offset each li ne with a margin 1 e f t - ma r g i n spaceswide The total pagewidth isthis offset plus the 
width set with the -w option. 

Do not print a warning messagewhen an argument file cannot beopened. Fai Iure to open a file 
stili makes the exit status nonzero, however. 

Separate columns by the single character coi umn-separator, default tab, instead of spaces. 
Do not print the 5-line header and the 5-li netrailer that are normally on each page, and do not fili 
outthebottomsof pages(with blank linesorform feeds). 
Print unprintablecharacters in octal backslash notation. 
Print version informati on on standard output then exit. 
Set the pagewidth to page- wi d t h columns. The default is 72. 

GNU TextUtilities 

ps 

ps— Report process status 
SYNOPSIS 

ps [-] [lujsvmaxScewhrnu] [txx] [0[ + | -]kl [ [ + | -]k2 . . . ] ] [pids] 

Therearealso two longoptions: 
--sortX[+i-]key[,[+|-]key[,...]] 

- -help 

M orelong optionsareon theway... 
D ESC RIFIO N 

ps givesasnapshot of thecurrent processes. If you want a repetitive update ofthis status, use top. This man pagedocuments 
the /proc-based version of ps, or tries to. 

COMMAND-LINE OPTIONS 

Command-lineargumentsmay optionally bepreceded by a -, butthereisno need forit. Therearealso some longoptions in 
GNU style; see the foli owi ng subsection forthose. 



1 Long format. 

u U ser format: gives username and start time. 

j Jobs format: pgid sid. 

s Signal format, 

v vm format. 

m Displaysmemory information (combinewith p flag toget number ofpages). 

f Forest fami lytree format forcommand line. 

a Show processes of other users too. 

x Show processes without controlling terminal. 

s Add child cpu timeand pagefaults. 

c C ommand name from task struct. 

e Show environment after command li ne and +. 



-n[number-separator 
[digits]] 

-0 I e f t - ma r g i n 

-r 

-s[col umn- separator ] 
-t 

-v 

- -version 
-w page - wi dt h 



pr 




w Wideoutput: don't torneate command linestofiton oneline. 

h N o header. 

r Running procsonly. 

n N umeric output for user and wchan. 

txx Only proeswith controll ingtty xx; use for xx thesamelettersasshown in then fidd. The 

tty namemust Pegiven immediately after theoption, with no intervening space, for 
example, ps -tvi. 



0[+| -]ki [,[+|- ]k2 [,...]] Order the process listing according to the multi level sort specified Py the sequenceof short 

keysfrom sort keys, k i , k 2 , ... . Default order specifications exist for each of thevarious 
formatsof ps. Theseareoverridden Py auser-specified ordering. The+ isquite optional, 
merely reiterating the default direction on a key. - reverses direction only on thekey it 
precedes. Aswith t and pids, theo option must Pethelast option in a single command 
argument, Put specifications in successive arguments are catenated. 

pids List only the specified processes; they are comma-deli mited. The list must Pegiven 

immediately after the last option in asinglecommand-lineargument, with no intervening 
space, for example, ps -ji,4,5. Lists specified in suPsequent arguments are catenated, for 
example, ps -11,23,4 5 ewill listali of the processes 1-6 in longformat. 

LONG COMMAND-LINE OPTIONS 

T hese options are preceded Py a douPle hyphen. 

--sortx[+|-]key[, Choose a multi letter key from thesoRTKEYs section.x may Peanyconvenientseparator 

[ + ! - ] key [ ,...]] character. To beGN U-ish, use=. The+ isreally optional Pecause default direction is 

increasing numerical or lexicographic order. Example: 

ps -jax -sort=uid, -ppid,+pid 

--heip Get a help messagethat summarizestheusageand givesa list of supported sort keys. This 

list may Pe more up-to-date than thisman page 

SORT KEYS 

Notethatthevaluesused in sorting are the internai valuesps usesand notthe"cooked" valuesused in some of the output 
format fields. If someonewantsto volunteer to write special comparison functionsfor thecooked values,... ;-) 



Short 


Long 


D escripti on 


c 


cmd 


Simplenameof executaPle 


c 


cmdline 


Full command line 


f 


flags 


Flags as in longformat F field 


g 


pgrp 


Process group ID 


G 


tpgid 


Controllingtty process group 1 D 


j 


cutime 


Cumulative user time 


J 


cstime 


Cumulative system time 


k 


utime 


User ti me 


K 


stime 


System time 


m 


min_f lt 


N umPer of minor pagefaults 


M 


ma j_f lt 


N umPer of major pagefaults 


n 


cmin_f lt 


Cumulativeminorpagefaults 


N 


cmaj_flt 


C umulati ve major page faults 


0 


session 


Session ID 


P 


pid 


Process ID 



continues 
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Short 


Long 


D eszri pti on 


p 


DDid 

rr 


Parent process ID 


r 


rss 


Resident set size 


R 


resident 


Resident pages 


g 


size 


M emory size in kilobytes 


s 


share 


Amount of shared pages 


t 


tty 


Theminor devicenumber of tty 


T 


start_time 


T i m e process was start ed 


U 


uid 


U ser 1 D number 


u 


user 


U sername 


V 


vsize 


Total VM size in bytes 


y 


priority 


Kernel scheduli ng priority 



FIELD DESCRIPTIONS 

pri Thisisthecounterfield in thetask struct. It isthetime in hz of the process's possible ti meslice. 

ni Standard UN IX nicevalue; a positive valuemeansless cpu time 

size Virtual imagesize; sizeof text+data+stack. 

rss Resident set size kilobytes of program in memory. 

wchan N ameof the kernel function where the process issleeping, with thesys stripped from thefunction name. If 

/boot/psdatabase does not exist, it isjust a hex number instead. 
stat Information about the status of the process. The first fi eld is r for runnable, s for sleeping, d for uni nterrupti ble 

sleep, t for stopped or traced, or z for a zombie process. The second fi eld containsw if the process hasno resident 

pages. Thethird field ìsn if the process has a positive nicevalue (ni field). 
tt Controllingtty. 

page in N umber of major page faults (page faultsthat cause pages to beread from disk, including pages read from the 

buffer cache). 
trs Text resident size. 

swap Kilobytes (or pages if -p isused) on swap device 
share Shared memory. 

UPDATING 

This proc-based ps worksby readingthefilesin theproc filesystem, mounted on /proc.Thisps does not need to besutd 
kmem or haveany privilegesto run. Do notgivethisps any special permisaons 

You will need to update the /boot/psdatabase fileby running /usr/sbin/psupdate to get meaningful information from the 
wchan field. Thisshould bedoneevery timeyou compileanew kernel. 

NOTES 

Themember usedjnath of task_struct isnot shown, sincecrto.s checksto seeif math is present. This causes the matti flag 
to be set for ali processes, and so it isworthless. 

Programsswapped out to disk will be shown without command-linearguments, and unlessthec option isgiven, in 
parentheses. 

%cpu shows the cputi me/ realti me percentage. It will not add up to 100 percent unlessyou arelucky. It istimeused divided 
by the ti me the process has been running. 

The size and rss fieldsdon'tcount the page tables and the task struct of a proc; this isat least 12k of memory thatis 
always resident. size isthevirtual sizeof theproc (code+data+stack). 



psidtopgm 




BUGS 

tty names are hard-coded: virtual consoles arevi, v2,... ; serial lines are s o and si; pty's are ppo, p p 1 ... pqo, pqi, ... . 
AUTHORS 

ps was ori gi nally written by Branko Lankester (iankeste@fwi.uva.ni) M ichael K. Johnson (johnsonm9sunsite.unc.edu) 
rewroteit significante to usetheproc filesystem, changingafew thingsin theprocess. M ichael Shidds 
(mjshieid®nyx.cs.du.eciu) added the multiple -pids feature. Charles Blake(cbiakeiucsd.edu) added multi level sorting and is 
thecurrent maintainerof theproc-ps suite. 

Cohesi ve Systems 27 J uly 1994 



psbb 

psbb— Extract bounding boxfrom PostScript document 



SYNOPSIS 

psbb file 

D ESC RIPTIO N 

psbb readsf i i e, which should bea PostScript document conformingto the document structuringconventions and looksfor 
a%%BoundingBox comment. If itfindsone, it printsa line 

llx lly urx ury 

on the standard output and exitswith zero status. If it doesn't find such a li ne or if the line is invai id, it printsa message and 
exitswith nonzero status. 

SEEALSO 

grops(l) 

G roff Version 1.09, 6 August 1992 



psidtopgm 

psidtopgm— Convert PostScript imagedata into a portablegraymap 
SYNOPSIS 

psidtopgm width height bits/sample [imagedata] 

DESCRIPTION 

psidtopgm reads the image data from a PostScript fi le as input and produces a portablegraymap as output. 

This isa very simpleand limited program, and ishereonly becauseso many people haveasked for it. To useit you haveto 
manually extract the readhexstring data portion from your PostScript file, and then givethewidth, height, and bits/sample 
on thecommand line. Beforeyou atterri pt this, you should at least read thedescription of the image operator in the PostScript 
LanguageReferenceM anual. 

It would probably not betoo hard to write a script that uses this fi Iter to read a speci fi c vari ety of PostScript image but the 
variation istoo greatto makeageneral-purposereader. Unless, of course, you want to write a fui l-f ledged PostScript 
interpreter... 

SEEALSO 



pnmtops(l), pgm(5) 
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AUTHOR 

Copyright© 1989 by J ef Poskanzer. 

2 August 1989 

pstopnm 

pstopnm— C onvert a PostScript file into a portableanymap 
SYNOPSIS 

pstopnm [-forceplain] [-help] [-llx s][-lly s ] [-landscape] [-portrait] [-nocrop] 
[-pbm |-pgm ]-ppm][-urx s][-ury s ] [-verbose] [-xborder n ] [ -xmax n][-xsize f] 
[-yborder f][-ymax n] [-ysize n] psfile[.ps] 

D ESC RIFIO N 

pstopnm reads a PostScript file as input and produces portableanymap filesas output. Thisprogram isjustauseful shell script 
that runsGhostScriptto render a PostScript into oneor morepnm files. pstopnm will create as many filesas the numberof 
pagesin thePostScriptdocument. If the input file isnamed pstiie.ps, the nameof the files will bepsfiieooi .ppm, 
psfn.ie002.ppm, and so on. 

The program mapsa rectangular portion of thePostScriptdocument into an image fi le accordi ngto thecommand-line 
opti ons. The selected area will always becentered in the output file, and may have borders around it. The image area to be 
extracted from the PostScript fi le and rendered into a portableanymap isdefined by four numbers, thelower-left corner and 
the upper-ri ght corner x and y coordinate^. Thesecoordinates are usuai ly speci fi ed by theBoundingBox comment in the 
PostScript file header, but they can beoverridden by the user by specifying oneor moreof thefollowing flags: -ìix, -ìiy, 
-urx, and -ury. The presence and thicknessof aborderto beleft around the image area is controlied by the use of the flags 
-xborder and -yborder. If BoundingBox parameters are not found, and image area coordinatesarenot specified on the 
command line, default valuesareused. U nless both output file width and height are specified viathe-xsize and -ysize 
flags, the program will map the document into the output image by preservi ng its aspect ratio. 

OPTIONS 

-torcepiain Forces the output fileto bea plain (in otherwords, nof'raw") portableanymap. 

-heip Printsthecommand syntax. 

-ìix bx Selectsbx as the lowerleft corner x coordinate (in inches). 

-ìiy by Selectsby as the lower left corner y coordinate (i n inches). 

-landscape Rendersthe image in landscape mode 

-portrait Renders the image in portrait mode. 

-nocrop Doesnot crop the output image di mensi ons to match the PostScript image area dimensions. 

-pbm -pgm -ppm Selects the format of the output fi le. By default, ali files are rendered as portablepixmaps(ppm format). 

-urx tx Selectstx astheupper-rightcornerxcoordinate(in inches). 

-ury ty Selectsty asthe upper-right corner y coordinate (in inches). 

-verbose Prints processing information to stdout. 

-xborder frac Specifies that the border width alongtheY axisshould befrac times the document width as specified by 

thebounding box comment in the PostScript file header. The default value ise.i. 

-xmax xs Specifies that the maxi mum output image width should haveasizelessorequal to xs pixels (default: 612). 

-xsize xs Specifies that the output imagewidth must beexactly xs pixels. 

-yborder frac Specifies that the border width along theX axisshould befrac times the document width as specified by 

thebounding box comment in the PostScript file header. The default value is 0.1. 

-ymax ys Specifies that the maxi mum output image height should have a size less or equal to ys pixels (default: 792). 

-ysize ys Specifies that theoutput image height must be exactly ys pixels. 



pstree 




BUGS 

The program will produce incorrect resultswith PostScript files that initi alize the current transformation matrix. In these 
cases, page translati on and rotation will not haveany effect. To render these files, probably the best bet isto usethefollowing 
flags: 

pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps 

Additional flags may Peneeded if thedocument issupposed to Perendered on a medium different from letter-sizepaper. 
SEEALSO 

gs(l), pstofits(l) 

COPYRIGHT 

Copyright© 1992 Smithsonian Astrophysical OPservatory. PostScript is a trademark of AdoPe Systems Inc. 
AUTHOR 

Alberto Accomazzi, WIPL, Center forAstrophysics 

28 Decemberl992 



pstree 

pstree— D isplay a tree of processes 
SYNOPSIS 

pstree [-a] [-0] [-h] [-1] [-p] [-u] [pi d| user ] 

D ESC RIFIO N 

pstree showsrunning processes as a tree. The tree isrooted at either pid or init if pid isomitted. If a username is specified, 
ali process trees rooted at processes owned Py that user areshown. 

pstree visually merges identical Pranches Py putti ng them in square Prackets and prefixing them with the repetition count; 
for example, 

init-+-getty 
I -getty 
I -getty 
1 -getty 

Pecomes 

init- -4*[getty] 

OPTIONS 

-a Show command-linearguments. If thecommand I i ne of a process isswapped out, that process isshown in 

parentheses. -a implicitly disables compaction. 
-c D isaPle compaction of identical suPtrees. By default, suPtreesarecompacted whenever possiPle. 
-h H ighlight the current process and its ancestors. This is a no-op if the terminal doesn't support highlightingor if 

neither the current process nor any of its ancestors are i n the suPtree Peing shown. 
-ì D isplay long lines. By default, linesaretruncated to the display width or 132 if output issentto a non-tty or if 

the display width isunknown. 
-p Show pids. pids are shown as deci mal numPersin parentheses after each process name. -p implicitly disaPles 

compaction. 

-u Show uid transitions. Whenever the uid of a process differs from theuid of its parent, thenew uid isshown in 
parentheses after the process name. 
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FILES 

/proc Location oftheproc filesystem 
AUTHOR 

Werner Al mesberger (aimesber@di.epfi. oh) 
SEEALSO 

ps(l), top(l) 

Linux, 11 October 1994 

psupdate 

psupdate— U pdatethe ps database of kernel offsets 
SYNOPSIS 

psupdate [system path] 

D ESC RIPTIO N 

psupdate updatesthe /boot/psdatabase fileto correspond to thecurrent kernel image system mapfile, /usr/src/iinux/vmiinux 
by default. 

OPTIONS 

If your system mapfile isnot /usr/src/iinux/vmiinux, you may givethenameof an alternate mapfile on thecommand line. 
FILES 

/boot/psdatabase 
/usr/src/ linux/ vmlìn 

SEEALSO 

ps(l), top(l), utmp(5) 

AUTHORS 

Originai codewritten by Branko Lankaster, horribly munged by M ichael K. Johnson in a desperate effort to add /etc/ 
psdatabase support to procps. Someday, itshould be rewritten, and thesupport in ps for alternate n ameli stsadded. Anyone 
want to volunteer to be added to the "Authors" section? 

C ohesi ve Systems 15 September 1993 

qrttoppm 

qrttoppm— Convert output from the Q RT ray tracer i nto a portable pixmap 
SYNOPSIS 

qrttoppm [qr t f i I e ] 

D ESC RIFIO N 

qrttoppm readsaQRT file as input and produces a portable pixmap as output. 



ranlib 




SEEALSO 

ppm(5) 

AUTHOR 

Copyright® 1989 byjef Poskanzer. 

25 Auguà 1989 

quota 

quota— Display disk usageand limits 
SYNOPSIS 

quota [ -guv | q ] 
quota [ -uv | q ] user 
quota [ -gv | q ] group 

D ESC RIFIO N 

quota displaysusers' disk usageand limits By default, only the user quotasareprinted. 

-g Print group quotasfor the group of which the user is a member. The optional -u flag isequivalentto the default, 
-v Will display quotason filesystemswhereno Storage is allocateci. 

-q Print a more terse message, containingonly information on filesystemswhereusageisover quota. 
Specifying both -g and-u displaysboth the user quotas and the group quotas(for the user). 

Only the superuser may usethe-u flag and theoptional user argumentto view the I imits of otherusers. N on-superuserscan 
use the -g flag and optional group argument to view only the limits of groupsof which they aremembers. 

The-q flag takes precedence over the -v flag. 

quota reports the quotas of ali thefilesystemslisted in /etc/fstab. For fi lesystems that areN FS-mounted, a cali to the 
rpc.rquotad on the server machine is performed to get the information. If quota exitswith a nonzero status, oneor more 
fi lesystems are over quota. 

FILES 

quota. user Located at the f i lesystem rootwith user quotas 

quota. group Located at the f i lesystem rootwith group quotas 

/etc/fstab To fi nd fi I esystem names and locati ons 

SEEALSO 

quotactl(2), fstab(5), edquota(8), quotacbeck(8), quotaon(8), repquota(8) 

8 January 1993 

ranlib 

raniib— G enerate i ndex to archive 
SYNOPSIS 

ranlib [ -v|-V] archi ve 



Parti: U ser Commands 
D ESC RIFIO N 

raniib generate an index to thecontentsof an archi ve and storesit in the archi ve. The index listseach symbol defined by a 
member of an archivethat isa rei ocatableobject file. 

Youmayusenm -sornm --print-armap to listthisindex. 

An archi ve with such an index speedsup linkingto the library, and allows routinesin the library to cali each otherwithout 
regard to their placement in thearchive 

TheGNU raniib program is another form ofGNU ar; running raniib iscompletely equivalent to executing ar -s. 
OPTIONS 

-v Printtheversion numberof raniib and exit 
SEEALSO 

binutiis entry in info; TheGN U BinaryU tilities, Roland H . Pesch (October 1991); ar(i); nm(i). 

COPYING 

Copyright© 1991 F ree Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof this manual under the conditionsfor verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission noticeidentical to thisone. 

Permission isgranted to copy and distri bute translationsof this manual into another language, under the above condì ti ons 
for modifi ed versi ons, except that this permission noticemay beincluded in translationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

Cygnussupport, 5 N ovember 1991 

rasttopnm 

rasttopnm— C onvert a Sun raster file into a portable anymap 
SYNOPSIS 

rasttopnm [rastfi I e ] 

D ESC RIFIO N 

rasttopnm reads a Sun raster fi le as i nput and produces a portable anymap as output. The type of the output fi le depends on 
the input file— if it's black and white, apbm fileiswritten; elseif it's grayscale, a pgm file; elseappm file. The program tei Is you 
which type it is writing. 

SEEALSO 

pnmtorast(l), pnm(5) 

AUTHOR 

Copyright © 1989, 1991 byjef Poskanzer. 

13 January 1991 



rawtoppm 

rawtopgm 

rawtopgm— Convert raw grayscale bytes into a portablegraymap 
SYNOPSIS 

rawtopgm [ -headerskip N][-rowskip N ] [ -tb | -topbottom] [tv dt h hei ght ][i magedata] 

D ESC RIPTIO N 

rawtopgm reads raw grayscale bytes as input and produces a portablegraymap as output. The input file is just grayscale bytes. 
If you don't speci fy the width and height on thecommand line, the program will check thesizeof theimageand try to make 
a quadrati c imageof it. It isan errar to supply a non-quadratic image without specifying width and height. The maxvai is 
assumed to be255. 

OPTIONS 

-headerskip If the fi le has a header, you can usethisflagto skipoverit. 

-rowskip If therei s paddi ngat the endsof the rows, you can skip it with thisflag. N otethat rowskip can bea real 

number. Amazingly, I oncehad an image with 0.376 bytes of paddi ng per row. Thisturned out to bedue 
to afiletransfer problem, but I was stili ableto read theimage. 

-tb -topbottom F li ps the imageupside down. The first pixel in apgm fi le is in thelower-left corner of theimage. For 

conversi on from imageswith the first pixel in theupper-left corner (for example, theM olecular Dynamics 
and Leicaconfocal formats), thisflipstheimageright.Thisisequivalentto rawtopgm [file] i pnmtiip 

-tb. 

BUGS 

If you don't specify the image width and height, the program will try to read theentireimageto a memory buffer. If you get 
a messagethat states that you are out of memory, try to specify the width and height on thecommand line. Also, the -tb 
option consumes much memory. 

SEE ALSO 

pgm(5), rawtoppm(l), pnmflip(l) 

AUTHORS 

Copyright® 1989 byjef Poskanzer; modifiedj une 1993 by 0liverTrepte(oiiver@fysik4. kth.se). 

15 Junel993 

rawtoppm 

rawtoppm— Convert raw RGB bytes into aportablepixmap 
SYNOPSIS 

rawtoppm[ -headerskip N][-rowskip N] [ -rgb| -rbg| -grb j -gbr ] -brg ] -bgr ] 
[ -interpixel] -interrow] width height [i magedata] 

DESCRIPTION 

rawtoppm reads raw RGB bytes as input and produces aportablepixmap as output. The input file is just RGB bytes. You have 
to specify the width and height on thecommand line because the program obviously can'tgetthem from thefile. The maxvai 
isassumed to be255. If the resulti ng image isupside down, run itthrough pnmmp -tb. 
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OPTIONS 

-headerskip If the file has a header, you can usethisflagto ski p over i t. 

-rowskip If thereis paddi ngat the endsof therows, you can skip itwith thisflag. 

-rgb -rbg -grb -gbr -brg -bgr T heseflags let you specify alternate color orders. T he default is -rgb. 

-interpixei -intembw T hese flags let you specify how thecolorsareinterleaved. The default is -mterpixei, 

meaning interi eaved by pixel. A byteof red, a byteof green, and a byteof blue orwhatever 
color order you specified. -ìntemow means interleaved by row— a row of red, a row of 
green, a row of blue, assumi ng standard RGB color order. An -mterpiane flag— ali the red 
pixels, then ali the green, then ali the blue— would bean obviousextension, but isnot 
implemented. You could getthesameeffect by splitti ng the fi le i nto threeparts(perhaps 
usi ng dd), turning each part into a PGM fi le with rawtopgm, and then combiningthem with 

rgb3toppm. 



SEEALSO 

ppm(5), rawtbpgm(l), rgb3toppm(l), pnmflip(l) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

6 February 1991 



rcp 

rcp— Remote fi le copy 
SYNOPSIS 

rcp [ -px] [ -k realm] f il el f i I e 2 

rcp [ -px] [ -r] [ -k Ar realm] file ... directory 

D ESC RIFIO N 

rcp copiesfiles between machines. Each fileor directory argument iseither a remote fi lenameof the form rname@rhost:path, 
or a locai filename (contai ni ng no : characters, or a / beforeany : characters). 

-r If any of the sourcefiles are directories, rcp copies each subtree rooted atthat name; in this case the desti nation 

must bea directory. 

-p Causesrcp to attemptto preserve (duplicate) in its copies the modification timesand modesof the sourcefiles, 
ignori ng the umask . By default, the mode and owner of f i i e 2 arepreserved if it already existed; otherwise, the 
mode of the source file modifi ed by the umask 2 on the desti nation hostisused. 

-k Requests rcp to obtain ti cketsfor the remote host in realm rea 1 m instead of the remote host's realm as determi ned 

by krb_realmof host 3. 

-x Turnson DES encryption for ali data passed by rcp. This may impact responsetimeand CPU utilization, but 
providesincreased security. 

If path isnot a full pathname, it isinterpreted relative to theiogin directory of the specified user ruser on rhost, or your 
currentusernameif no other remote usernameis specified. A path on a remote host may bequoted (using \, ", or ') so that 
the meta characters are i nterpreted remotely. 

rcp doesnot promptfor password? it performs remote execution via rsh(l), and requiresthesameauthorization. 
rcp handlesthird- party copies, where neither source nor target filesareon thecurrent machine. 



rcs 




SEEALSO 

cp(l), ftp(l), rsh(l), rlogin(l) 

HI STORY 

The rcp command appeared in BSD 4.2 . Theversion of rcp descri bed herehas been reimplemented with Kerberos in BSD 
4.3 Reno. 

BUGS 

Doesn't detect ali cases in which the target of a copy might beafilewhen only a directory should be legai. 
Isconfused byany output generated by commandsin a or file on the remote host. 

Thedestination usernameand hostnamemay haveto bespecified asmost.rname when the desti nati on machine isrunning 
the BSD 4.2 version of rcp. 

BSD 4.3r, 27 July 1991 



rcs 

rcs— C hange RC S fi le attri butes 
SYNOPSIS 

rcs opti o n s file ... 

D ESC RIFIO N 

rcs createsnew RCSfilesor changes attri butes of existing ones. An RCS file contai ns multiple revisions of text, an access list, 
a changelog, descri pti ve text, and some control attri butes. For rcs to work, the caller's login namemust beon the access 
list— unless the access list isempty, the Caller istheowner of the fi le or thesuperuser, or the -i option ispresent. 

Pathnamesmatchingan RCS suffix denote RCS files; ali others denote working fi les. N amesarepaired asexplained in ci(l). 
Revision numbersusethesyntax descri bed in ci(l). 

OPTIONS 



-i 


Create and initializea new RCSfile, butdo notdepositany revision. If the RCS file has no path prefix, try 




to place it first into the subdirectory ./rcs, andthen into the cu rrent directory. If the RCS file already 




exists, print an errar message. 


-al ogi ns 


Append the login namesappearing in thecomma-separated listi ogi ns to theaccess list of theRC S file. 


-Ao 1 d f i 1 e 


Append theaccess list of oi df 1 1 e to theaccess list of the RCS file. 


-e[l ogi ns ] 


E rase the login namesappearing in thecomma-separated list i ogi ns from theaccess list of the RCS file If 




ogi ns is omitted, erase the enti re access li st. 


-b [ r e v ] 


Set the default branch to rev.lf rev is omitted, the default branch is reset to the (dynamically) highest 




branch on thetrunk. 


-estri n g 


Set the comment leader to stri ng. An initial ci.oran rcs -i without-c, guesses the comment leader from 




the suffix of the working fi lename. 



This option isobsolescent, si nce RC S normally uses the precedi ng$i_og$ line's prefix when inserti ng log linesduring 
checkout(seeco(l)). H owever, older versionsof RCS use the comment leader instead of the$i_og$ line's prefix, so if you pian 
to access a file with both old and new versionsof RCS, makesure its comment leader matches its$i_og$ line prefix. 

-ksubst Set the default keyword substitution to subst . Theeffect of keyword substitution is descri bed in co(l). 

Givingan explicit-k option to co, rcsdiff.and resmerge overridesthisdefault. Bewarercs -kv, because 
-kv is incompatiblewith co -ì. Use rcs -kkv to restare the normal default keyword substitution. 
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i[rev] Lock the revision with number r ev . If a branch isgiven, lock the latest revision on that brandi. If r e v is 

omitted, lock the latest revision on the default branch. Locking preventsoverlappingchanges. If someone 

elsealready holds the lock, the lock isbroken aswith rcs -u. 
u[r ev ] Unlock the revision with number rev. If a branch isgiven, unlock the latest revision on that branch. I f r e v 

isomitted, rem ove the latest lock held by the Caller. N ormally, only the lockerof a revision can unlock it. 

Somebody else unlocki ng a revision breaks the lock. T his causes a mai I message to be sent to the originai 

locker. T he message contai ns a commentary solicited from thebreaker. Thecommentary is termi nated by 

end-of-fileor by a line contai ning a period by itself. 
l Set locking to strict. strict locking means that the owner of an RCS file isnot exempt from locking for 

checkin. Thisoption should beused for files that are shared. 
u Set locking to non -strict. non -stnct locking means that the owner of afileneed not lock a revision for 

checkin. Thisoption should not beused for files that are shared. Whether default locking is strict is 

determined byyour system administrator, but it isnormally strict. 

mr ev: msg Replace revision rev'S log message with msg. 

m Donotsend mail when breaking somebody else's lock. Thisoption is not meant for casual use; itismeant 

for programs that warn usersbyother means, and invoke rcs -u onlyasalow-level lock-breaking 
operation. 

nname [: [rev ]] Associate the symbol ic namename with the branch or revision rev. Delete the symbol ic nameif both : and 
rev areomitted; otherwise, printan errar message ifn a me is already associateci with another number. If rev 
issymbolic, itisexpanded before association. A rev consisti ng of a branch number followed by a period 
standsforthecurrent latest revision in the branch. A : with an empty rev standsforthecurrent latest 
revision on the default branch, normally the trunk. For example, rcs -nname: rcs/* associatesi me with 
thecurrent latest revision of ali thenamed RCSfiles; this contrasts with rcs -nname :$ rcs/*, which 
associ atesname with the revision numbersextracted from keyword stringsin the corresponding working 
files. 

Nn a me [ : [r e v ]] Act I i ke -n, except override any previous assignment of n a me . 

orange D eletes ("outdates") the revisions given by range. A range consisti ng of a single revision number means 

that revision. A range consisti ngof a branch number means the latest revision on that branch. A range of 
theform revi: rev2 means revisions r e v 1 torev2 on the same branch, :rev meansfrom thebeginningof 
thebranch contai ning r ev up to and including rev, and rev : meansfrom revision rev to theend of the 
branch contami ng rev. N oneof theoutdated revisions can have branches or locks 

q Run quietly; do not print diagnosti cs. 

i Run interactively, even if the standard input isnot a terminal. 

ss t a t e [ :r e v ] Set the state attribute of the revision r ev tostate. If rev isabranch number, assumethe latest revision on 
that branch. If rev isomitted, assume the latest revision on the default branch. Any identifier i s acceptabl e 
for state. A useful set of states isExp (for experimental), stab (for stable), and Rei (for released). By 
default, ci(l) sets the state of a revision to Exp. 

t[f i i e ] Writedescriptivetextfrom thecontentsof thenamed n le into the RCS file, deleting the existing text. 

Thef i i e pathnamecannot begin with -. If f i i e isomitted, obtain thetext from standard input, 
terminated by end-of-fileor byalinecontainingaperiod by itself. Promptforthetextif interaction is 
possi ble; see-i. With -i, d escripti ve text is obtai ned even if -t isnot given. 

t-st ri ng W rite descri ptive text from the stri n g into the RCS fi le, deleting the existing text. 

t P reserve the modificati on timeon the RCS file unless a revision isremoved. Thisoption can suppress 

extensi ve recompilation caused by a make(l) dependency of some copy of the working fi le on the RCS file. 
Use thisoption with care; it can suppress recompilation even when it isneeded, that is, when achangeto 
the RCS file would mean achangeto keyword stri ngs in the working file. 

v Print RCS'sversion number. 

vn Emulate RCSversion n. Seeco(l) fordetails. 

xsuffixes Usesuffixes to characterize RC S files. See ci(l) for detai Is. 

zzone Usezone as the default ti mezone. T his option hasno effect; it is present for compati bility with other RCS 

commands. 



roclean 




At least oneexplicit option must begiven, to ensure compati bi lity with future planned extensionsto thercs command. 
COMPATIBILITY 

The-brev option generatesan RCSfilethat cannot beparsed by RCS versi on 3 or earlier. 

The-ksubst options(except -kkv) generate an RCSfilethat cannot beparsed by RCS version 4 or earlier. 

Usercs -vn to makean RCS fileacceptableto RCS version n by discarding information thatwould confuse version n. 

RCS version 5.5 and earlier doesnot support the -x option, and requiresa ,v suffixon an RCS pathname. 

FILES 

rcs accessesfiles much ascì(l) does, exceptthat it uses the effective user forali accesses, it does notwrite the working file or 
its directory, and it doesnot even read the working fi le unless a revision number of $ isspecified. 

ENVIRONMENT 

RcsiNiTfi [:rev] 0 ptions prepended to theargument list, separated by spaces. Seeci(l) for details. 
DIAGNOSTICS 

The RCS pathname and therevisionsoutdated arewritten to the diagnostic output. The exit status is zero if and only if ali 
operati ons were successful. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.13; Release D ate: 1995/06/05. 

Copyright 1982, 1988, 1989 W alter F. Tichy. 

Copyright 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 

SEEALSO 

rcsintro(l), co(l), ci(l), ident(l), rcsclean(l), rcsdiff(l), rcsmerge(l), rlog(l), rcsfìle(5) 

"RCS— A System for Version Control" by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

BUGS 

A catastrophe(for example, a system crash) can cause RC Sto leavebehind asemaphorefilethat causes later invocati ons of 
RCSto claim that the RCS file is in use. To fixthis, remove the semaphore fi le. A semaphore file's nametypically begins 
with a comma or ends with an underscore. 

Theseparator for revision rangesin the-o option used to be- instead of :, butthisleadsto confusion when symbolic names 
contain -. For backwardscom pati bi lity, rcs -o stili supports the old - separator, but itwarnsaboutthis obsolete use. 

Symbolic names need not referto existing revisionsor branches. For example, the-o option doesnot remove symbolic names 
fortheoutdated revisions; you must use -n to rem ove the names. 
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rcsclean 

rcsciean— Clean up worki ng files 
SYNOPSIS 

rcsclean [opt ons ] [f il e . . . ] 
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D ESC RIFIO N 

rcsciean removes files that are not being worked on. rcsciean -u also unlocksand removesfilesthat arebeingworked on 
but havenotchanged. 

Foreach f i i e given, rcsciean compares the working fi le and a revision in thecorresponding RCSfile If itfindsadifference, 
itdoesnothing. Otherwise, it fi rstunlocks the revision if the -u option isgiven, and then removes theworkingfileunless the 
working fi le is writable and the revision islocked. Itlogsitsactionsby outputting thecorresponding rcs -u and ™ -f 
commandson the standard output. 

Files are pai red asexplained in c±(l). If no file isgiven, ali working files in thecurrent directory arecleaned. Pathnames 
matchingan RCS suffix denote RCS files; ali others denote working files. 

The numberof the revision to which the working fi le iscompared may beattached to any of theoptions-n, -q, -r, or-u. If 
no revision number isspecified, then if the -u option isgiven and the Caller hasone revision locked, rcsciean usesthat 
revision; otherwise, rcsciean usesthelatest revision on the default branch, normally theroot. 

rcsciean isuseful for clean targetsin makefiles. Seealso rcsdiff(l), which printsoutthedifferences, and ci(l), which 
normally revertsto the previ ous revision if afilewasnot changed. 

OPTIONS 

-ksubst U se s ubs t -style keyword substitution when retrieving the revision for comparison. Seeco(l) for details. 

-n[rev] Do not actually remove any files or unlock any revisions. Usingthis option will teli you what rcsciean 

would dowithout actually doingit. 

--q[rev] Do not log the actionstaken on standard output. 

--r[rev] This option hasno effect otherthan specifying the revision for comparison. 

-t Preserve the modificati on timeon the RCS file even if the RCS file changes becausea lock isremoved. 

Thisoption can suppressextensive recompilation caused by amake(l) dependencyof some other copy of 
the working fi le on the RCS file. Use this option with care; it can suppress recompilation even when it is 
needed, thatis, when thelock removal would mean achangeto keyword stringsin theother working file. 

-u[rev ] U nlock the revision if it islocked and no differenceisfound. 

-v Print RCS'sversion number. 

-vn EmulateRCSversion n. Seeco(l) for details. 

-xsuffixes U se s li f f i x e s to characterize RC S files. See ci(l) for detai Is. 

-zzone Usezone asthetimezonefor keyword substitution; see co(l) for details. 

EXAMPLES 

rcsciean *.c *.h removesall workingfiles ending in .c or.h that were not changed si ncetheir checkout. 
rcsciean removesall working files in thecurrent directory that were not changed si ncetheir check-out. 

FILES 

rcsciean accesses files much asci(l) does. 
ENVIRONMENT 

rcsinit Optionsprependedto the argument list, separated byspaces. A backslash escapesspaceswithin an option. The 
rcsinit optionsareprepended to theargument listsof most rcs commands. U seful rcsinit options i nclude -q, 
-v, -x, and -z. 



DIAGNOSTICS 

T he exit status is zero if and only if ali operationsweresuccessful. M issi ng working files and RCS files are si lently ignored. 



reseli ff 



FI 



IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 1.12; Release D ate: 1993/11/03. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993 Paul Eggert. 

SEEALSO 

ci(l), co(l), ident(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), rcsfile(5) 

"RCS— A System for Version Control" by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

BUGS 

At least onef i i e must begiven in older U N IX versionsthat do not provi de the needed directory scanning operations. 
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resdiff— Compare rcs revisions 
SYNOPSIS 

resdiff [ -ksubst ][-q ] [ -rr evi [ -rr e v 2 ]][-T ][-V[n]][-xsuffi xes ][-zzone ] 
[di f f options ] f i I e . . . 

DESCRIPTION 

resdiff runsdiff(l) to compare two revisions ofeach RCS fi le given. 

Pathnamesmatchingan rcs suffix denote RCS fi les; ali others denote working files. N amesarepaired asexplained in ci(l). 

Theoption -q suppressesdiagnostic output. Zero, one, or two revisions may bespecifi ed with -r. Theoption -ksubst affeets 
keyword substitution when extracting revisions, asdescribed in co(l); for example, -kk -n.i -n .2 ignoresdifferences in 
keyword valueswhen comparing revisions 1.1 and 1.2. To avoid excess output from locker name substitution, -kkvi is 
assumed if at most one revision option is given, no -k option is given, -kkv is the default keyword substitution, and the 
working fi le's mode would beproduced by co -1. Seeco(l) for detailsabout -t, -v, -x, and -z. Otherwise, ali options of 
diff(l) that apply to regular filesareaccepted, with thesamemeaning asfor diff. 

If both r ev 1 and rev2 areomitted, resdiff comparesthelatest revision on the default branch (by default the trunk) with the 
contents of the corresponding working fi le. This is useful for determi ni ng what you changed si nce the last checkin. 

If r ev 1 is given, but r e v 2 isomitted, resdiff compares revision r evi of the RCS fi le with the contents of the corresponding 
working fi le. 

If both r ev 1 and r ev 2 aregiven, resdiff compares revisions r evi and r ev 2 of the RCS file. 
Both r ev 1 andrev2 maybegiven numeri cally or symbolically. 

EXAMPLE 

Thecommand 

resdiff f.c 

comparesthelatest revision on the default branch of the RC S file to the contents of theworking filet .e. 
ENVIRONMENT 

rcsinit 0 ptions prepended to theargument list, separated by spaces. Seeci(l) for details. 
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DIAGNOSTICS 

Exit status i s 0 for no differences duri ng any comparison, 1 forsomedifferences, 2 for trouble. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.5: Rdease D ate: 1993/11/03. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993 Paul Eggert. 

SEEALSO 

ci(l), co(l), diff(l), ident(l), rcs(l), rcsintro(l), rcsmerge(l), rlog(l) 

"RCS— A System for Version Control" by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 
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rcstreeze— Freeze a configurati on of sourceschecked in under RCS 
SYNOPSIS 

rcsfreeze [name] 

D ESC RIPTIO N 

rcsfreeze assigns a symbol ic revision numberto asetof RCSfilesthatform avalid configuration. 

Theidea isto run rcsfreeze each timea new version ischecked in. A uniquesymbolic name(c_number, where number is 
increased each time rcsfreeze isrun) isthen assigned to the most recent revision of each RCSfileof the mai n trunk. 

An optional name argumentto rcsfreeze givesasymbolic nameto the configuration. The unique identifier is stili generated 
and islisted in the log file, but itwill not appear aspart of the symbol ic revision name in theactual RCSfiles. 

A log message isrequested from the user for future reference. 

Theshell script worksonly on ali RCSfilesat onetime. Ali changed files must bechecked in already. Run rcsciean(l) first 
and seewhether any sources remai n in the current directory. 

FILES 

rcs/. rcsfreeze. ver Version number 

rcs/. rcsfreeze. log Log messages, most recent first 

AUTHOR 

Stephan V. Bechtolsheim 

SEEALSO 

co(l), rcs(l), rcsclean(l), rlog(l) 

BUGS 

rcsfreeze does not check whether any sources are checked out and modified. 

Although both sourcefilenamesand RCS filenamesareaccepted, they are not paired as usuai with rcs commands. 
Errar checking isrudimentary. 



resi ntro 




resfreeze isjust an optional example shell script, and should not betaken too seriously. Seecvs fora more complete 
solution. 
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rcsintro 

rcsintro— Introduction to rcs com mands 
D ESC RIFIO N 

TheRevision Control System (RCS) manages multiple revisionsof files. RCS automates the stori ng, retri eval, logging, 
identification, and merging of revisions. RCS isuseful fortextthat isrevised frequently; for example programs, documenta- 
tion, graphics, papers, and form lettera 

The basic user interface isextremely si mple. The novi ce only needsto learn two commands: ci(l) and co(l). ci, short for 
check in, depositsthecontentsof afileinto an archival filecalled an RCSfile. An RCS file contains ali revisionsof a 
parti cular file, co, short for check out, retrieves revisions from an RCSfile. 

FUNCTIONSOFRCS 

Stare and retrieve multiple revisions oftext. RCSsavesall old revisions in aspace-efficientway. Changesno longer destroy 
theoriginal becausetheprevious revisions remain accessi ble. Revisionscan beretrieved accordingto rangesof revision 
numbers, symbolic names, dates, authors, and states. 

Maintain a complete history of changes RCS logsall changesautomatically. Besidesthetext of each revision, RCS stores 
theauthor, the date and timeof checkin, and a log messagesummarizing thechange The logging makes it easy to find out 
what happened to a modulewithout having to compare source listings or having to track down colleagues. 
Resolve access confliets W hen two or moreprogrammerswish to modify the same revision, RCS alertstheprogrammers 
and preventsonemodification from corrupting the other. 

Maintain a treeof revisions RCS can maintain separate li nesofdevelopment for each module. It stores a treestructurethat 
represen ts th e ancestral relationships among revisions. 

M erge revisions and resolve confliets Two separate linesof development of a module can becoalesced by merging. If the 

revisions to bemerged affect the samesectionsof code, RCSalerts the user about the overlapping changes. 

Control releasesand configurations Revisionscan beassigned symbolic names and marked asreleased, stable, experimen- 

tal, and so on. With thesefacilities, configurations of modulescan bedescribed simply and directly. 

Automati cally identify each revision with name, revision number, creation time, author, and so on. T he identification 

islikeastamp that can beembedded at an appropriate place in thetext of a revision. The identification makes it si mple to 

determinewnich revisionsof which modules makeup a given configuration. 

M inimize secondary Storage RCS needs little extra space for the revisions (only the differences). If intermediate revisions 
aredeleted, thecorrespondingdeltasarecompressed accordi ngly. 

GETTING STARTED WITH RCS 

Suppose you have a file f .c that you wish to put under control of RCS. If you havenot al ready doneso, makean rcs 
directory with thecommand: 

mkdir RCS 

Then invoke the check in command: 
ci f.c 

This command createsan RCS file in the rcs directory, stores f .c into itas revision 1.1, and deletest .c. It also asksyou for 
a description. T he descri ption should bea synopsisof thecontentsof the fi le. AH later check in commands wi II ask you fora 
log entry, which should summarize the changes that you made. 
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Files in theRcs directory arecalled RCSfiles; theothersarecalled working files. To get back the working fi le f .c in the 
previ ousexample, use the check out command: 

co f.c 

This command extractsthe latest revision from the RCS file and writesit into f.c. If you want to edit f.c, you must lock it 
asyou check itoutwith thecommand: 

co -1 f.c 

You can now edit f.c. 

Suppose after some editi ng you want to know what changes that you have made. T he command: 

rcsdiff f.c 

tei Is you thedifference between themost recently checked-in versi on and the working fi le. You can check the fi le back in by 
invoking 

ci f.c 

This increments the revision number properly. 
If ci compiai nswith the message: 

ci error: no lock set by your name 

then you havetried to check in afileeven though you did not lock itwhen you checked it out. Of course, it istoo late now 
to do thecheckoutwith locking, becauseanothercheckoutwould overwriteyour modifications. Instead, invoke 

rcs -1 f.c 

This command will lock the latest revision for you, unlesssomebody elsegot ahead of you already. In that case, you'll haveto 
negotiatewith that person. 

Locking assures that you, and only you, can check in the next update, and avoidsnasty problems if several peoplework on 
the same file. Even if a revision is locked, it can stili be checked out for reading, compi ling, and so on. Ali that locking 
prevents is a check-in by anybody but the locker. 

If your RCS file is private— if you are the only person who isgoing to deposi t revisionsinto it— strict locking isnot needed 
and you can turn it off. If strict locking isturned off, theowner of the RCS file need not have a lock for checkin; ali others 
stili do. Turning strict locking off and onisdonewith the commands rcs -u f.c and rcs -Lf.c. Ifyou don'twantto 
clutter your working directory with RCSfiles, create a subdirectory called rcs in your working directory, and move ali your 
RCSfilesthere rcs commands will look first into that directory to find needed files. AH the commands di scussed herewill 
stili work, without any modificati on. (Actually, pairsof RCS and working files can bespecified in threeways: both aregiven, 
only the working fi le is given, or only the RC S file is given. Both RC S and working fi les may have arbitrary path prefixes rcs 
commands pairthem up intelligently.) 

To avoid thedeletion of the working fi le duri ng checkin (in case you want to continue editing or compi ling), invoke 

ci -1 f.c or ci -u f.c 

These commands check in f.c as usuai, but perform an implicit checkout. The first form also locks the checked in revision, 
thesecond onedoesn't. Thus, these optionssave you one checkout operation. The first form isuseful ifyou wantto 
continue editing, thesecond oneif you just wantto read thefile. Both update the identifi cation markersin your working 
file. (Seethefollowing subsection, "Automatic Identification.") 

You can giveci the number you want assigned to a checked in revision. Assume ali your revisionswerenumbered 1.1, 1.2, 
1.3, etc, and you would liketo start release 2. Thecommand: 

ci -r2 f.c or ci -r2.1 f.c 

assigns the number 2.1 to thenew revision. From then on, ci will number the subsequent revisi ons with 2.2, 2.3, and so on. 
Thecorrespondingco commands: 
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co -r2 f.c 

and 

co -r2.1 f.c 

retrieve the latest revision numbered 2.xand the revision 2.1, respectively. co without a revision number selectsthelatest 
revision on thetrunk, that is, the highest revision with a number consisti ng of two fields. N umberswith morethan two 
fields are needed for branches. For example, to start a branch at revision 1.3, invoke 

ci -r1 .3.1 f.c 

Thiscommand starts a branch numbered 1 at revision 1.3, and assignsthe number 1.3.1.1 to thenew revision. For more 
information about branches, see rcsf ue(5). 

AUTOMATIC IDENTIFICATION 

RCScan put special stri ngs for i denti fi cation into your sourceand object code. To obtain such identification, place the 
marker: 

$Id$ 

into your text, for instance inside a comment. RCS will replace this marker with a stri ng of theform: 

$Id: fi lena me reni si on date t i me author state $ 

With such a marker on the first pageof each module, you can always see with which revision you are working. RCS keeps 
the markers up-to-date automatically. To propagate the markers into your object code, simply put them into literal character 
stri ngs. In C, thisisdoneasfollows: 

static char rcsid[] = "$Id$"; 

Thecommand idem extracts such markers from any file, even object code and dumps. Thus, idem letsyou find out which 
revisionsof which moduleswereused in agiven program. 

You may also find it useful to put the marker $i_og$ into your text, inside a comment. This marker accumulates the log 
messagesthat arerequested during checkin. Thus, you can maintain the complete history of your file di rectly inside it. There 
areseveral additional identification markers; seeco(l) for details. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.3; Release D ate: 1993/11/03. 
Copyright© 1982, 1988, 1989 Walter F. Tichy. 
Copyright© 1990, 1991, 1992, 1993 Paul Eggert. 

SEE ALSO 

ci(l), co(l), ident(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l) 

"RCS— A System for Version Control" by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 
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rcsmerge— M erge RCS revisions 
SYNOPSIS 

rcsmerge [options] file 
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D ESC RIFIO N 

rcsmerge i ncorporates the changes between two revisionsof an RCSfileinto the corresponding working fi le. 

Pathnamesmatchingan rcs suffix denote RCS fi les; ali others denote working files. N amesarepaired asexplained in ci(l). 

At leastone revision must bespecified with oneof the options described in thenext subsection, usually -r. At mosttwo 
revisionsmay bespecified. Ifonlyone revision isspecified, the latest revision on the default branch (normally the highest 
branch on thetrunk) isassumed forthesecond revision. Revisionsmay bespecified numerically or symbolically. 

rcsmerge pri nts a warning if th ere are o veri aps, and deli mits the overlapping regi ons asexplained in merge(l). Thecommand 
isuseful for i ncorporating changes into a checked-out revision. 

OPTIONS 

-a Output conflictsusingthe-A styleof diff3(l), ifsupported by diff3. This mergesall changes leading 

from fiie2 to fiie3 into fiiei, and generates the most verbose output. 
-e, -e These options specify conflict stylesthat generate less information than -a. Seediff3(l) for details. The 

default is -e. W ith-e, rcsmerge doesnotwarn about confi icts. 
-ksubst Uses ubst -style keyword substitution. Sea co(l) for details. For example, -kk -n.i -n.2 ignores 

differences in keyword valueswhen merging the changes from 1.1 to 1.2. It normally does not makesense 

to merge binary files asif they weretext, so rcsmerge refusesto merge files if-kb expansion isused. 
-p[r ev ] Send theresult to standard output i nstead ofoverwriting the working fi le. 

-q [ r e v ] Run quietly; do not pri nt diagnosti cs. 

-r[rev ] M ergewith respect to revision r e v . H erean empty r e v stands for the latest revision on the default branch, 

normally the head. 

-t This option hasno effect; it ispresentfor compati bi li ty with other rcs commands. 

-v Print RCS's version number. 

-vn Emulate RCS version n. Seeco(l) for details. 

-xsuffixes U se s li f f i x e s to characterize RC S files. See ci(l) for detai Is. 

-zzone Usezone asthetimezonefor keyword substitution. Seeco(l) for details. 

EXAMPLES 

Suppose you havereleased revision 2.8 off .c. Assume, furthermore, that after you complete an unreleased revision 3.4, you 
receiveupdatesto release2.8 from someoneelse. To combine the updatesto 2.8 and your changes between 2.8 and 3.4, put 
theupdatesto 2.8 into fi le -f .c and execute 

rcsmerge -p -r2.8 -r3.4 f.c >f.merged.c 

Then examinef .merged.c. Alternati vely, if you want to save the updatesto 2.8 in the RCS file, check them in as revision 
2.8.1.1 and execute co -j: 

ci -r2.8.1 .1 f.c 

co -r3.4 -]2. 8:2. 8.1 .1 f.c 

Asanother example, thefollowingcommand undoes the changes between revision 2.4 and 2.8 in your currently checked out 
revision in f.c: 

rcsmerge -r2.8 -r2.4 f.c 

Note the orderof thearguments, andthatf.c will beoverwritten. 
ENVIRONMENT 

rcsinit Opti ons prepended to theargument list, separated by spaces. Seeci(l) for details. 



DIAGNO STICS 

Exit status is a for no overlaps, 1 for someoverlaps, 2 for trouble. 
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IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.6; Rdease D ate: 1995/06/01. 

Copyright© 1982, 1988, 1989 Walter F. Tichy. 

Copyright© 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert. 

SEEALSO 

ci(l), co(l), ident(l), merge(l), rcs(l), rcsdiff(l), rcsintro(l), rlog(l), rcsfile(5) 

"RCS— A System for Version Control" by Walter F. Tichy, software-Practice & Experience 15, 7 (July 1985), pages 
637-654. 
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rdist— Remote fi le distri bution program 
SYNOPSIS 

rdist [ -nqbRhivwy] [-f distfile] [ -d v a r =v a I ne ] [-mhost] [name ...] 
rdist [-nqbRhivwy] -c name ... [login@host:dest] 

D ESC RIFTIO N 

rdist is a program to maintain i denti cai copi esoffi leso ver multiple hosts. It preservestheowner, group, mode, and mtime 
of filesif possi ble and can update programsthat areexecuting. rdist readscommandsfrom distfile to direct the updating 
offiles and/or directories. 

0 ptions specific to the fi rst synopsis form: 

If distfile is-, the standard input isused. 
-f distfile U se the specified distfile. 

If eitherthe -f or - option isnot specified, theprogram looks fi rst for distfile, then Distfile to use as the input. If no 
names are specified on thecommand line, rdist will update ali of thefilesand directories li sted in distfile. Otherwise, the 
argument istaken to be the name of afileto beupdated or the label of acommand to execute. If label and fi lenames confi ict, 
it isassumed to bea label. Thesemay beused together to update specific files usi ng specific commands. 

0 ptions specific to thesecond synopsis form: 

-c Forces rdist to interprettheremainingargumentsasasmall distfile. 

Theequivalent distfile is as follows 
name ... -i login@ host instali dest ; 

0 ptions common to both forms: 

-b Binary compari son. Perform a binary compari son and update files if they differ rather than compari ng 

dates and sizes. 

-d var =v a i ue D efine va r to nave vai ne. The -d option isused to define or override variable defi nitions in the distfile. 

vai ue can betheempty stri ng, onename, or a list of names surrounded by parenthesesand separated by 
tabs and/or spaces. 

-h Follow symbolic links Copy thefilethat the link pointsto rather than thelink itself. 

-i Ignoreunresolved links, rdist will normally try to maintain the link structure offiles bei ng transferred and 

warn the user if ali the links cannot befound. 
-mhost Limitwhich machines areto beupdated. M ulti pie -m argumentscan begiven to limitupdatesto a subset 

of the hosts li sted in the distfile. 
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-n Print the commands without executing them. Thisoption isuseful for debugging distf ile. 

-q Quiet mode. Filesthat are bang modified arenormally printed on standard output. The - q option 

suppresses this. 

-R Remove extraneous fi les. If a directory isbeing updated, any filesthat exist on the remote hostthat do not 

exist in the master directory are removed. This isuseful for maintainingtruly identical copiesof di recto- 
ri es. 

-v Verify that the fi les are up-to-date on ali thehosts. Any filesthat are out-of-datewi II bedisplayed, but no 

fi les wi 1 1 bechanged nor any mail sent. 

-w Wholemode. Thewholefilenameisappended to the desti nati on directory name. N ormally, only thelast 

component of a nameisused when renamingfiles. T hi s wi 1 1 preserve the directory structureof the fi les 
bei ng copi ed instead of flattening the directory structure. Forexample, renaming a list of filessuch as 

diM/f1 dir2/f2 tO dir3 WOuId Create files dir3/dir1/f1 and dir3/dir2/f2 instead Of dìr3/f1 and dir3/f2. 

-y Younger mode Files arenormally updated if their mtimeand size(seestat(2)for moredetails) disagree. 

The -y option causes rdist notto update fi les that are younger than the master copy. This can beused to 
prevent newer copieson other hostsfrom being replaced. A warning messageis printed for fi les that are 
newer than the master copy. 

distfiie contai nsasequenceof entri es that specify thefilesto be copi ed, the desti nati on hosts, and whatoperationsto 
perform to do theupdating. Each entry hasoneof thefollowing formats: 

<variable name>'=' <name list> 

[label: ]<source list> '->' <destination listxcommand list> 
[label: ]<source list> '::' <time_stamp f ilexcommand list> 

The first format isused for defining variables. The second format isused for di stri buting fi lesto other hosts. The third 
format isused for making li stsof filesthat havebeen changed sincesomegiven date. The source list specifi es a li st of files 
and/or di rectorieson the locai hostthat areto beused as the master copy for di stributi on. The desti nation list is the list of 
hosts to whi eh thesefi les areto be copi ed. Each file in the source list isadded to a list of changes if thefi le is out-of-date on 
the hostthat isbeing updated (second format), or the fi le is newer than thetimestamp file(third format). 

Labels are optional. They areused to identify a command for parti al updates. 

N ewlines, tabs, and blanks are only used as separato rs and areotherwiseignored. Comments begin with # and end with a 
newline. 

Variables to beexpanded begin with $ followed by onecharacter or a nameenclosed in curly braces(seetheexamplesat the 
end). 

The SOUrce and desti nation listS have thefollowing format: <name> or '(' <zero or more names separated by white-space> 
')'■ 

T he shell meta characters [,],{,},*, and ? arerecognized and expanded (on the locai host only) in thesameway ascsh(l). 
They can beescaped with a backslash. The ■ character isalso expanded in thesameway ascsh(l) but isexpanded separately 
on the locai and desti nation hosts. W hen the -w option isused with a filmarne that beginswith ", everythingexcept the 
home directory isappended to the desti nation name. Filenamesthat do not begin with / or " use the desti nation user'shome 
directory as the root di rectory for the rest of the fi lename. 

The command list consi stsof zero or more commands of thefollowing format: 

'instali' <options> opt_dest_name ';' 
' notif y ' <name list> ' ; 
'except' <name list> ' ; 
'except_pat' <pattern list> ';' 
'special' <name list> string ';' 

The instali command isused to copy out-of-date fi les and/or di rectories. Each source fi lei scopi ed to each host in the 
desti nation list. D irectories are recursively copied in thesameway. opt_dest_name isan optional parameterto renamefiles. If 
no instali command appearsin the command list or the desti nation name is not specifi ed, the source fi lename isused. 




D irectories in thepathnamewill becreated if the/ do not exist on the remote host. To help prevent disasters, a nonempty 
directory on a target host wi II never bereplaced with a regular file or a symbolic link. H owever, under the -r option, a 
nonempty directory wi II beremoved if the corresponding filename is completely absent on the master host. The options are 
-r, -h, -i, -v, -w, -y, and -b and have the samesemanticsas options on thecommand lineexcept they only apply to thefiles 
in thesource list. The login nameused on the desti nati on host isthesameas the locai host unless the desti nati on nameisof 
the format iogin@host. 

Thenotify command isused to mail the list of filesupdated (and any errorsthat may haveoccurred) to thelisted names. If 
no e appearsin menarne the desti nati on host isappended to thename(for example, namei^host, name2(?host). 

Theexcept command isused to update ali of thefiles in thesource list except for the files listed in name list . Thisisusually 
used to copy everything in a directory except certain files. 

The except jat command is li ke the except command except that pattern list isa list of regular expressions(seeed(l) for 
details). If oneof thepatternsmatchessomestringwithin afilename, that fi le wi II beignored. Note that because\ isaquote 
character, it must bedoubled to becomepart of the regular expression. Variablesareexpanded in pattern list, but notshell 
file pattern-matching characters. To include a $, it must beescaped with \. 

The special command isused to specify sn(l) commands that areto be executed on the remote host after the fi le in name 
list isupdated or instali ed. If the name list is omitted, then the shell commands wi II be executed for every file updated or 
installed. Theshell variable file i s set to thecurrent filename beforeexecuting the commands in string . string startsand 
endswith doublé quotes(") and can cross multi pie lines in distme . M ultiple commands to theshell should beseparated by 
a semi colon. Commands are executed in the user's home directory on the host being updated. The speci al command can be 
used to rebuild private databases, and so on after a program has been updated. 

Thefollowing isa small example: 

HOSTS = ( matisse root@arpa ) 

FILES = ( /bin /lib /usr/bin /usr/games 

/usr/ include/ {*.h,{st and, sys.vax*, pascal, machine} /*.h 

/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) 

EXLIB = ( Mail. re aliases aliases.dir aliases.pag crontab dsbre sendmail.cf 
sendmail.fc sendmail.hf sendmail.st uucp vfont ) 

${FILES} -> ${HOSTS} instali -R ; except /usr/lib/${EXLIB} ; except /usr/games/lib ; 
special /usr/lib/sendmail " /usr/lib/sendmail -bz" ; 

sres: /usr/sre/bin -> arpa except pat ( \\.o\$ /SCCS\$); 

IMAGEN = (ips dviimp catdvi) 

imagen: /usr/local/${IMAGEN} -> arpa instali /usr/local/lib ; notify ralph ; 
${FILES} :: stamp.cory notify root@cory ; 

FILES 

disttiie Input command file 

/tmp/rdist* Temporary filefor update lists 

SEEALSO 

sh(l), csh(l), stat(2) 



HI STORY 

Therdist command appeared in BSD 4.3. 
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DIAGNOSTICS 

A complaint about mismatch of rdist version numbers may really stem from some problem with starti ngyoursh di; for 
example, you are in too many groups. 

BUGS 

Sourcefilesmust resideon thelocal hostwhere rdist isexecuted. 

Thereisno easy way to have a special command executed after ali fi lesi n a directory havebeen updated. 
Variableexpansion only worksfor namelists; there should bea general macro facility. 
rdist abortson fi lesthat have a negative mti me (beforejan 1, 1970). 

There should bea torce option to allow replacement of nonempty directoriesby regular filesor symlinks. A meansof 
updating file modes and ownersof otherwise identical filesisalso needed. 

BSD 4.3, 30Decemberl993 



reconfig 

recontig— Convert old Xconfigto new XF86C onfig 
SYNOPSIS 

reconfig < Xconfig > XF86Config 

D ESC RIFIO N 

The recontig program converts the Xconfig fi le format used in XFree86 versions priorto 3.1 into the XF86C onfig format 
currently used. The XF86C onfig format contai ns more information than the Xconfig format, so manual editing is required 
after converting. 

SEEALSO 

XFree86(l), XF86Conf ig(4/5), xf 86conf ig(l) 

AUTHOR 

Gertjan Akkerman 

BUGS 

Comment lines are stri pped out when converting. 

XFree86 Version 3.1.1 
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ref 

ref— D isplay a C function header 
SYNOPSIS 

ref [ -t] [ -x] [ -c class]... [-f file]... tag 

D ESC RIPTIO N 

ref quickly locatesand displays the header of a function. To do this, ref looksin the tags fileforthelinethat describes the 
function, and then scans the source fi le for the function. W hen it locates the function, it displays an introductory comment 
(if there isone), thefunction'sdeclaration, and thedeclarationsof ali arguments. 

SEARCH METHOD 

ref usesafairly sophisticated tag look-up algorithm. If you supply afilenamevia -f file, then eivis first scans the tags 
fi le for a stati c tag from that file. This search islimited to the tags file in thecurrent directory. 

If you supply a class name vi a -c class, then elvis searchesfor a tag from that class. This search isnot limited to the 
current directory; You can supply a list of directories in the envi ronment vari able tagpath, and ref will search through the 
tags fi le in each directory until it findsatag in the desi red class. 

If that fai Is, ref will then try to look up an ordinary global tag. This search checksall of the directories li sted in tagpath, too. 
If the tag being sought doesn't contai n any colons, and you haven't given a -x fiag, then any static tags in a tags fi le will be 
treated as global tags. 

Ifyou've given the -t fiag, then ref will simply output the tag li ne that itfound, and then exit. Without -t, though, ref 
will search for the tag line It will try to open the source fi le, which should be in the same directory asthetagsfilewherethe 
tagwasdiscovered. If the source fi le doesn't exist, or isunreadable, then ref will try to open afilecalled refs in that 
directory. Eitherway, ref will tryto locate thetag, and display whatever itfinds. 

INTERACTION WITH elvis 

ref isused by theeivis snift-K command. If the cursor islocated on aword such assplat, in thefiletoo.c, then elvis will 
invoke ref with thecommand ref -f foo.c spiat. 

If eivis hasbeen compiled with the -dexternal_tags flag, then elvis will use ref to scan the tagsfiles. This is slower than 
thebuilt-in tagsearching, but it al lows elvis to access the more sophisticated tag lookup provided by ref. Other than that, 
external tags should actexactly like internai tags. 

OPTIONS 

-t Output tag info, instead of thefunction header. 

-f file Thetag might bea static function in file. You can useseveral -f flagsto have ref consider static tags 

from more than onefile. 

-c class Thetag might bea member of class class. You can useseveral -c flagsto haveref consider tags from 

more than oneclass. 

FILES 

tags List of function names and their locations, generated by ctags 
refs Function headers extracted from source files (optional) 

ENVIRONMENT 

tagpath Listof directoriesto besearched.Theelementsinthelistareseparated by either semicolons(for M S-DOS, 

Atari TOS, and AmigaDos), or by colons (every other operati ng system). For each operati ng system, ref 
hasabuilt-in default which isprobably adequate. 
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NOTES 

You might want to generate a tags fi le for the di rectory that contains the source code for standard C I i brary on your system. 
If licensing restrictionsprevent you from making the library source readableby everybody, then you can havectags generate 
a refs file, and make refs readable by everybody. 

If your system doesn't comewith the li brary source code, then perhapsyou can produce somethingworkable from theiint 
libraries. 

SEEALSO 

elvis(l), ctags(l) 

AUTHOR 

Steve K i rkendal I (kirkenda@cs . pdx . edu) 

reset 

reset— Reset the terminal 
SYNOPSIS 

clear 

DESCRIPTION 

reset callstput(l) with the clear, rmacs, rmm, rmui, rsi, rs2, and rs3 arguments. T his causes tput to send appropriate 
reset stringsto the terminal based on information in /etc/termcap (for the G N U or BSD tput) or in theterminfo database 
(forthencurses tput). T his sequence seems to besufficientto reset the Linux VC'swhen they start printing "funny- 
looking" characters. For good measure, stty(l) iscalled with the sane argument in an attemptto get Cooked mode back. 

SEEALSO 

reset(l), stty(l), tput(l) 

AUTHOR 

Rik Faith (faith@cs.unc.edu) 

Linux 0.99, 10 October 1993 

resize 

resize— Set termcap and terminal settingsto current xterm window size 
SYNOPSIS 

resize [ -u | -c ] [ -s [ r ow col ] ] 

DESCRIPTION 

resize printsashell command for setti ng the terni and termcap environment variablesto i ndicate the current size of xterm 
window from which the command isrun. For this output to takeeffect, resize must either beevaluated aspart of the 
command li ne (usuai ly donewith ashell alias or function) or else redi rected to a fi le that can then beread in. From theC 
shell (usuai ly known as /bin/csn), thefollowing alias could bedefined in theuser's.csnrc: 

% alias rs 'set noglob; eval 'resize 11 

After resizing the window, the user would type: 

%rs 



rgb3toppm 




Usersof versionsof the Bourneshell (usually known as/bin/sh) thatdon't havecommand functionswill need to send the 
output to atemporary file and theread it back in with the . command: 

$ resize > /tmp/out 
$ . /tmp/out 

OPTIONS 

Thefollowingoptionsmaybeused with resize: 

-u Thisoption indicete that Bourneshell commandsshould begenerated even if theuser'scurrent 

Shell isn't /bin/sh. 

-c Thisoption indicates that C shell commandsshould begenerated even if the user's current shell 

isn't /bin/csh. 

-s [rows coiumns] T his option indicate that Sun console escape sequences wi II be used instead of the special xterm 
escape code. If rows and c o umns aregiven, resize wi 1 1 ask the xterm to resize itself. However, the 
window manager may chooseto disallow thechange. 

FILES 

/etc/termcap For the base termcap entry to modify 
"/.cshrc User'saliasforthecommand 

SEEALSO 

csh(l), tset(l), xterm(l) 

AUTHORS 

M ark Vandevoorde(M IT-Athena), Edward M oy(Berkeley) 
Copyright© 1984, 1985 by XConsortium 
SeeX(l) for a complete copyright notice. 

BUGS 

The -u or -c must appear to theleftof -s if both are specified. 

X Versi on 11 Re!ease6 



rev 

re v— Reverse li nes of a file 
SYNOPSIS 

rev [file] 

D ESC RIFIO N 

The rev utility copies the specified filesto the standard output, reversi n g the order of charactersin every line. If no filesare 
specified, thestandard input isread. 

21 M arch 1992 



rgb3toppm 

rgb3toppm— Combinethree portablegraymapsinto oneportablepixmap 
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SYNOPSIS 

rgb3toppmr ed pg mf i I e greenpgmfi I e bl uepgmf i I e 

D ESC RIPTIO N 

rgb3toppm reads three portable graymaps as input and combine them and producesoneportablepixmapas output. 
SEEALSO 

ppmtorgb3(l), pgmtoppm(l), ppmtopgm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

15 February 1990 

rlog 

riog— Print log messagesand other informati on about RCSfiles 
SYNOPSIS 

rlog [ o p t i o n s ] f i I e ... 

DESCRIPTION 

riog prints information about RCS files. 

Pattinarne matchingan rcs suffix denote RCS files; ali others denote working files. N amesarepaired asexplained in ci(l). 

riog pri nts the foli ovvi ng information for each RCS file: RCS pathname, working pathname, head (thenumber of the latest 
revision on thetrunk), default branch, access list, locks, symbolicnames, suffix, total number of revisions, number of 
revisionsselected for printing, and descriptivetext. Thisisfollowed by entriesfortheselected revisions in reverse chronologi- 
cal order for each branch. For each revision, riog prints revision number, author, date/ ti me, state, number of linesadded/ 
deleted (with respectto the previous revision), locker of the revision (if any), and log message. Ali timesaredisplayed in 
Coordinated U ni versai Time (UTC) by default; thiscan beoverridden with -z. Without options, riog prints complete 
information. T he options below restri et this output. 

-l Ignore RCS fi les that haveno locks set. Thisisconvenient in combination with -h, -ì, and -r. 

-r Print only the nameof the rcs fi le. Thisisconvenient for translati ng a working pathname into an RCS 

pathname. 

-h Print only the RCS pathname, working pathname, head, default branch, access list, locks, symbolic names, 

and suffix. 

-t Printthesameas -h, plusthe descri ptive text. 

-n Do notprintthesymbolic names. 

-b Print information about the revisions on the default branch, normally thehighest branch on thetrunk. 

-ddat es Print information about revisions with a checkin date/ti me in therangesgiven by the semi colon- separated 

list of d a t es . A range of the form di<d2 or d2>di selects the revisions that were deposi ted between di and 
d2 exclusive. A range of the form <d or d> selects ali revisions earlier than d. A range of the form d< or>d 
selects ali revisionsdated later than d. If < or > isfollowed by =, then the ranges are inclusive, not exclusive. 
A range of the form d selects the single, latest revision dated d or earlier. The date/ti me stri ngsd, di, and 
d2 are in the f ree format explained in co(l). Quoti ng is normally necessary, especially for < and >. Note 
that the separator isa semicolon. 

-i[i ockers ] Print information aboutlocked revisions only. In addition, if thecomma-separated listi ockers of login 
namesisgiven, ignoreall locksotherthan thoseheld bythei ockers. Forexample, riog -l -r -ìwft 
rcs/* prints the nameof RCSfiles locked by theuserwft. 




-r[r evi si ons ] P ri nt informati on about revisi onsgiven in thecomma-separated list r evi s i ons of revisionsand ranges. A 
rangerevi: rev2 meansrevisionsrevi to rev2 on thesamebranch, :rev meansrevisionsfrom the 
beginningof thebranch up to and includi ng rev, and rev: means revisi ons starti ng with rev to the end of 
thebranch contai ning rev. An argument that isa branch means ali revisionson that branch. A rangeof 
branches means ali revisionson thebranches in that range. A branch followed by a . means the latest 
revision in that branch. A bare -r with no revisions means the latest revision on the default branch, 
normally thetrunk. 

-sst at es Print information about revisi ons whose state attributes match oneof thestatesgiven in thecomma- 

separated list s t a t e s . 

-w[i o g i ns ] Print information about revisions checked in by userswith login namesappearing in thecomma-separated 

list ìogins. If ìogins isomitted, theuser's login isassumed. 
-t Thisoption hasno effect; it is present for compati bili ty with other rcs commands. 

-v Print the RCS version number. 

-vn Emulate RCS version n when generati ng logs. (See co(l) for more details.) 

-xsuff i xes Usesuf f i xes to characterize RC S files. (Seeci(l) for details.) 

nog prints the intersection of the revisions selected with theoptions -d, -1, -s, and -w, intersected with theunion of the 
revisions selected by - band -r. 

-zzo ne Specifies the date output format, and specifies the default ti me zone for date in the -ddates option. The 

zone should beempty, a numeri c UTC offset, or the special stri ng ufor locai ti me. The default isan 
empty zone, which usesthetraditional RCS format of UTC without any ti mezone indicati on and with 
slashes separating the partsof the date otherwise, ti mes are output in iso 8601 format with timezone 
indication. Forexample, if locai timeisjanuary 11, 1990, 8 p.m. Pacific Standard Time, eight hourswest 
of UTC, then thetimeisoutputasfollows: 

option time output 



-z 1990/01/12 04:00:00 (default) 

-zLT 1990-01-11 20:00:00-08 

-z+05:30 1990-01-12 09:30:00+05:30 



EXAMPLES 

H ere are four riog commands: 

rlog -L -R RCS/* 
rlog -L -h RCS/* 
rlog -L -1 RCS/* 
rlog RCS/* 

Thefirst command prints the namesof ali RCS files in the subdirectory rcs that havelocks. The second command prints 
the headers of those files, and the third prints the headers plus the log messages of the locked revisions. The last command 
prints complete information. 

ENVIRONMENT 

rcsinit Opti ons prependedto the argument list, separated by spaces. (See ci(l) for details.) 



DIAGNOSTICS 

T he exit status is zero if and only if ali operationsweresuccessful. 
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IDENTIFICATION 

Author: Walter F. Ti chy 

M anual Page Revision: 5.9: Rdease D ate: 1995/06/16 

Copyright® 1982, 1988, 1989 W alter F. Tichy 

Copyright© 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert 

SEEALSO 

ci(l), co(l), ident(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rcsf ile(5) 

"RCS-A System forVersion Control" by Walter F. Tichy, Software-P radice & Experiencel5, 7 (July 1985), pages 637-654. 
BUGS 

Theseparatorfor revision rangesin the -r option used to be - instead of :, butthisleadsto confusion when symbolic names 
contain -. For backwards compati bility, nog -r stili supports the old - separator, but itwarnsaboutthisobsoleteuse. 

GNU, 16 Junel995 

rlogin 

nogin— Remote login 
SYNOPSIS 

rlogin [-8EKLdx] [-e char] [-k realm] [-1 username] h o s t 

D ESC RIFIO N 

nogin startsa terminal session on aremotehosthost . 

rlogin first attemptsto usetheKerberosauthorization mechanism, described in the followi ng subsection. If the remote host 
doesnotsupportKerberos, the standard Berkeley authorization mechanism isused. Theoptionsareasfollows: 

-8 The -8 option allowsan eight-bit input data path at ali times; otherwise, parity bits are stri pped exceptwhen the 

remote side's stop and start characters are other than "sro.. 
-e The - e option stopsany characterfrom bei ng recognized asan escape character. When used with the -8 option, 

thisprovidesacompletelytransparentconnection. 
-K The -k option turnsoff ali Kerberosauthentication. 

-l The -l option allowsthe rlogin session to berun in utout mode.(Seetty(4) fordetails). 

-d The -d option turnson socket debugging (seethe setsockopt(2) man page) on theicp socketsused for 

communication with the remote host. 
-e The - e option allowsuser specification of the escape character, which isthetilde(-) by default. Thisspecification 

maybeas aliterai character, or asan octal valuein theform nnnn. 
-k The -k option requests rlogin to obtain tickets for the remote host in realm reaim instead of the remote host's 

realm asdetermined by krb_reaimofhost(3). 
-x The -x option turnson D ES encryption for ali data passed via the nogin session. Thismay impact responsetime 

and CPU utilization, but provi desincreased security. 

A I ine of theform <escape cnar> disconnectsfrom the remote host. Similarly, theline<escape cnar>"z will suspend the 

rlogin session, and <escape charxdelayed -suspend char> SUSpendS the Send portion Of therlogin, but ali OWS Output 

from the remote system. By default, the tilde ( ~) character is the escape character, and normally control -y ("y) isthe 
delayed-suspend character. 

Ali echoingtakes place at the remote site, so that (except for delays) the nogin istransparent. Flow control via "s/"q and 
flushing of input and output on interrupts is handled properly. 



rm 




KERBERO S AU TH ENTIC ATIO N 

Each user may have a private authorization list in the fi le in hisor her home directory. Each line in this fi le should contain a 
Kerberosprincipal nameof theform principai.instance (@reaim). If the origi nating user is authenticated to one of the 
principals named, access isgranted to the account. Theprincipai accountname. (©ìocaireaim) isgranted access if thereis 
no file. Otherwise, a login and password will beprompted for on the remote machine as in ìogin(l). To avoid certain 
security probi ems, the fi le must beowned by the remote user. 

If Kerberosauthentication fails, a warning messageisprinted and the standard Berkeley riogin isused instead. 

ENVIRONMENT 

Thefollowing environment variable is utilized by riogin: 
term Determinestheuser'sterminal type 

SEEALSO 

rsh(l), kerberos(3), krb_sendauth(3), krb_realmof host(3) 

HI STORY 

The riogin command appeared in BSD 4.2. 
BUGS 

riogin will bereplaced by teinet(l) in the near future 
M ore of the environment should be propagated. 

BSD 4.2, 27 July 1991 

rm 

™— Remove files 
SYNOPSIS 

rm [-dfirvR] [--directory] [--force] [ - -interactive] [ - -recursive] 
[--help] [--version] [--verbose] name... 

D ESC RIFIO N 

Thismanual page documents the gnu version of rm. rm removeseach specified file. By default, it doesnot remove di rectories. 
If afileisunwritable, the standard input isa tty, and the -f or - - force option isnot given, rm prompts the user for whether 
to remove the fi le. I f the response does not begi n wi th y or y, the fi le is ski pped. 

GNU ™, likeevery program that usesthegetopt function to parse itsarguments, letsyou use the - - option to indicate that 
ali following argumentsarenonoptions. To remove a fi le cai led -f in thecurrent directory, you could type either 

rm - - -f 

or 

rm . / -f 

TheU N IX ™ program's use of a single - for this purpose predates the development of thegetopt standard syntax. 
OPTIONS 

-d, - - directory Remove directories with uniink instead of rmdir, and don't requ ire a directory to beempty before 
tryingto uniink it. Only worksforthesuperuser. Because unlinking a directory causes any files in 
the deleted directory to becomeunreferenced, it iswiseto fsck thefi lesystem after doingthis. 
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-f, --force Ignore nonexi stent files and na/er prompt the user. 

-i, - -mteractive Prompt whether to remove each file. If theresponsedoesnot begin with y or y, thefileisskipped. 

-r, -r, --recursive Remove the contents of di rectories recursively. 

-v, --verbose P ri nt the name of each file before removing it. 

- -heip Print ausagemessageon standard output and exit successfully. 

--version Print version information on standard output, then exit successfully. 

GNU FileU tilities 
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rmdir— Remove empty di rectories 
SYNOPSIS 

rmdir [-p] [--parents] [--help] [--version] dir... 

DESCRIPTION 

Thismanual page documents the GN U version of rmdir. rmdir removeseach given empty directory. If any nonoption 
argument does not refer to an existing empty directory, it is an errar. 

OPTIONS 

-p, - -parents Remove any parent directories that are explicitly mentioned in an argument, ifthey become empty 

after the argument file is removed. 
- -heip Print ausagemessageon standard output and exit successfully. 

--version Print version information on standard output, then exit successfully. 

GNU FileU ti I i ti es 

rmmod 

rmmod— U nload loadable modules 
SYNOPSIS 

rmmod [ - r ] module . . . 

DESCRIPTION 

rmmod unloads loadable modules from thekernel. 

rmmod triesto unload a set of modules from thekernel, with the restri ction thatthey are not in use and that they are not 
referred to by other modules. 

If morethan one module isnamed on thecommand line, the modules wi II be removed in the given order. Thissupports 
unloadingof stacked modules. 

With the opti on -r, a recursive rem ovai of modules wi II beattempted. Thismeansthat if a top module in astack isnamed 
on thecommand line, ali modules that areused bythis module wi II be removed aswell, if possi ble. 

SEEALSO 

insmod(l), lsmod(l), ksyms(l), modules(2) 
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HI STORY 

Themodulesupportwas first conceived byAnonymous (asfar asl know... ). Linux version by BasLaarhoven 
(bas@vimec.m), 0.99.14 version byjon Tombs( jon@gtex02.us.es), extended by Bjorn Ekwall (bjorn@biox.se). 

BUGS 

rmmod might have some, buttheyarewell hidden. 

Linux, 14 May 1995 



rnews 

rnews— Recei ve news from a U U C P connection 
SYNOPSIS 

rnews [ -h host ][-v ][-U ][-S master ][input ] 

D ESC RIFIO N 

rnews reads messagessent by a downstream uucp newsfeed and sendsthem to the locai InterN etN ews server. The messageis 
read from thespecified input file or standard input if no input is named. 

If the -s flag isused, then rnews wi 1 1 connectto thespecified host. If theflag isnotused, itwill tryto connectto the server 
by opening aU N IX-domain stream connection. If that fails, itwill tryto open a TCP connection to the default remote 
server. 

If the server isnotavailable, themessageisspooled into a new filecreated in the /var/spooi/ rnews directory. The -u flag 
may beused to send ali spooled messagesto the server when it becomesavailableagain, and can beinvoked regularly by 

cron(8). 

When sent over uucp, U senet articles are typically joined in a single batch to reduce the uucp overhead. Batchescan also be 
compressed, to reduce the communication ti me. If a messagedoes not start with a number sign (#) and an exclamati on 
point, then the enti re input istaken as a single news article. If it does start with thosetwo characters, then the first line is read 
and interpreted as a batch command. 

If thecommand is#i rnews nnn.wherennn is a number, then thenext nnn bytes (starti ng with the next line) are read as a 
news article. 

If thecommand is#! cunbatch, then therest of input isfed to thecompress(l) program with the -d flag to uncom press it, 
and the output of this pipeisread as input from rnews. T hi sisfor historical co m pati bili ty — th ere isno program named 
cunbatch. A compressed batch will start with a #! cunbatch line, then contai n a seriesof articles separated by #\ rnews nnn 
lines. 

If thecommand isany other word, then rnews will tryto execute a program with that namein the directory /news/bin/ 
rnews. The batch will befed into the program 's standard input, and the standard output will beread back as input into 

rnews. 

If rnews detects any problemswith an article, such asa missing header or an uni ntel ligi ble reply from the server, itwill savea 
copy of the article in the /var/spooi/ rnews /bad directory. If the - v flag isused, itwill print a noticeof ali such errorson the 
standard error, naming the input file(if known) and printing the first few characters of the input. Errorsarealwayslogged 
through sysiog(3). 

If the -h flag isgiven, orfailingthat, theenvironment variableuu_MACHiNE is set, then rnews will log theM essage-ID and 
host for each article offered to the server via sysiog(3). Logging will only bedoneif thevalueis not an empty string. 



BUGS 

rnews cannot process articles that haveembedded \es in them. 
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HISTORY 

Written by Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

innd(8). 

rpegen 

rpegen— An RPC protocol compiler 
SYNOPSIS 

rpegen infile 

rpegen [-D name[= value]] [-T] [-K secs] infile 

rpegen -o| -h| -1| -m| -t [-0 outfile] infile 

rpegen [-1] -s nettype [-0 outfile] infile 

rpegen -n netid [-0 outfile] infile 

D ESC RIFIO N 

rpegen isatool that generates C codeto implement an RPC protocol. The input to rpegen i s a I anguage si m i I ar to C known 
asRPC language (Remote Procedure Cali Language). rpegen isnormally used asin the first synopsiswhereit takesan input 
fileand generatesupto four output fi les. If themfiie isnamed proto, x, then rpegen will generate a header file in proto, n, 
xdr routinesin proto_xdr.c, server-side stubs in proto_svc.c, and client-side stubs in proto_cint.c. 

With the -Toption, it will al so generate the RPC dispatch tablein proto_tbi.i. W ith the - se option, it will also generate 
sample code that would illustrate howto use the remote procedureson theclient side. This code would becreated in 
protociient.c. With the - Ss option, it will also generate a sample server code that would illustrate howto writethe 
remote procedures. Thiscode would becreated in proto_server.c. Theserver created can bestarted both bytheport 
monitors (for example, inetd or ìisten) or by itself. W hen it isstarted by a port monitor, it creates servers only for the 
transportforwhich the file descri ptor 0 was passed. Thenameof thetransport must bespecified by setti ng up theenviron- 
mental variable pm transport. 

W hen theserver generated by rpegen isexecuted, it creates server handles for ali thetransports specified in netpath 
environment variable, or if it i s unset, it creates server handles for ali thevisibletransportsfrom /etc/netconfig file Note: 
thetransports are chosen at runtimeand not at compi le ti me. When theserver isself-started, it backgrounds itself by default. 
A special define symbol rpc_svc_fg can beused to run theserver processin theforeground. Thesecond synopsisprovides 
special features that allow for the creation of more soph isti cated RPC servers. Thesefeatures include support for user- 
provided #defines and RPC dispatch tables. Theentries in the RPC dispatch tablecontain 

■ Pointers to the servi cernuti ne correspondingto that procedure 

■ A pointer to the input and output arguments 

■ Thesizeof theseroutines 

A server can use the di spatch tableto check authorization and then to execute the service routine: a eli ent library may useit 
to deal with the detailsof Storage management and xdr data conversi on. The other threesynopsesshown in the precedi ng 
paragraph are used when one does not wantto generate ali theoutput files, but only a parti cular one. (Someexamplesof 
their usageis descri bed in the "Example" subsection.) W hen rpegen isexecuted with the -s option, it creates servers for that 
parti cular class of transports. W hen executed with the -n option, it creates a server for thetransport specified by netid. If 
infiie is not specified, rpegen accepts the standard input. The C preprocessor, ce -e (seecc(l) for details), isrun on the 
input file before it isactually interpreted by rpegen. For eachtypeof output file, rpegen defines a special preprocessor 
symbol for use by the rpegen programmer, as follows: 
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rpc_hdr Defined when compiling into header fi les 

rpc_xdr Defined when compiling into XD R routines 

rpc_svc Definedwhen compiling into server- si de stubs 

rpc_clnt Defined when compiling into client-side stubs 

rpc_tbl Defined when compiling into rpc dispatch tablesAny linebeginningwith % ispassed directly into the 

output file, uninterpreted by rpcgen. For every data type referred to in infiie, rpcgen assumesthat there 
exists a routine with the stri ng xdr prepended to the nameof the data type. Ifthis routine does not exist in 
theRPC/XDR library, it must beprovided. Provi di ng an undefined data type al lowscustomization of 
XDR routi nes. T he fol lowi ng options are avai lable 

-a Generate ali thefiles includi ng sample code for eli ent and server side 

-b Thisgenerates code for the SunOS4.1 styleof rpc. It isfor backwards compati bility. 

Thisis the default. 

-5 Thisgenerates code for the SysVr4 styleof rpc. Itisused by the Tran sport 

Independent RPC that isin Svr4 systems. By default, rpcgen generates code for 
SunOS4.1 type of rpc. 

-c Compile into XDR routines. 

-c Generate code in ANSI C. Thisoption also generates code that could becompiled 

with the C -H-compiler. Thisis the default, 
-k G enerate code i n K&R C.ThedefaultisANSI C. 

-Dname[ = v a i uè] D efine a symbol n a me . Equivalent to the#defìne di recti ve in the sou ree. If no vai ue 

isgiven, vai ue isdefined as 1. Thisoption may bespecified morethan once, 
-h Compile into C data-definitions (a header file), -t option can beused in conjunc- 

tion to produce a header fi le that supports RPC dispatch tables. 
-i Generate a service that can bestarted from inetc The default isto generatea static 

service that handles transports selected with -s. Using -i al lows starti ng a service by 

either method. 

-K secs By default, servi cescreated using rpcgen wait 120 seconds after servicing arequest 

before exiting. That interval can bechanged using the -k flag. To create a server that 
exitsimmediately upon servicing arequest, -k ocan beused. To create a server that 
neverexits, the appropri ateargument is -k -1. 

When monitoring for a server, someportmonitors, such asiisten(lM ), always 
spawn a new processin responseto a service request. If it isknown that a server wi II 
beused with such a monitor, the server should exit immediately on completi on. For 
such servers, rpcgen should be used with - k - 1 . 
-ì C ompile i nto client-side stubs. 

-m Compile into server- si de stubs, but do not generatea main routine. Thisoption is 

useful for doing callback-routinesand for userswho need to writetheir own main 
routine to do initialization. 

-n net i d Compi le into server-side stubs for the transport specified by net d. There should be 

an entry for net i d in thenetconfig database. Thisoption may bespecified more 
than once so asto compi le a server that serves multi pie transports. 

-n U se the newstyle of rpcgen. This allows procedures to have multiple arguments. It 

also uses the style of parameter passing that closely resembles C . So, when passing an 
argument to a remote procedure, you do not haveto pass a poi nter to theargument 
but theargument itself. Thisbehavior is di ff cren t from the old styleof rpegen- 
generated code The new style is not the default case because of backwards 
compati bility. 

-o outf i i e Specify the nameof the output file If none is specified, standard output isused (-c, 

-h, -ì, -m, -n, -s, -se, -ss, and -t modesonly). 
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-s nett ype Compileinto server-side stubs for ali thetransports belonging to the class nettype. 

The Supportai Classesarenetpath, visible, circuit_n, circuit_v, datagram_n, 

datagram_v, tcp, and udp. See rpc(3N ) forthemeaningsassociated with these 

classes. Thisoption may bespecified morethan once. Note: Thetransports are 

chosen at runtimeand not at compiletime. 
-se Generatesamplecodeto show the use of remote procedure and how to bind to the 

server before calli ng the client-side stubs generated by rpegen. 
-ss Generate skeleton code for the remote procedureson the server side. You would 

needtofill intheactual code for the remote procedures. 
-t Compileinto RPC dispatch table. 

-t G enerate the code to support RPC dispatch tables. The options -c, -h, -1, -m, u, 

and -t areused exclusively to generate a particulartypeof file, while the options - d 
and -t are global andean beusedwith the other options. 

NOTES 

The RPC languagedoes not support nesting of structures. Asaworkaround, structurescan bedeclared at the top levd, and 
their nameused inside other structures in order to achievethesameeffect. N ameclashescan occurwhen using program 
definitions because the apparent scopi ng does not really apply. M ostof these can beavoided by giving uniquenamesfor 
programs, versions, procedures, and types. The server code generated with the -n option refersto thetransport indicated by 
netid and henceisvery site-specific. 

EXAMPLE 

Thefollowingexample: 

$ rpegen -T prot.x 

gen erates fi ve fi I es: prot.h, prot_clnt.c, prot_svc.c, prot_xdr.c, and prot_tbl.i. 

Thisexample 

$ rpegen -h prot.x 

sendstheC data-defi nitions {header file) to thestandard output. 

To send th e test versi on of the -dtest, server-side stubs for ali thetransport belonging to theclassdatagranwi to standard 
output, use 

$ rpegen -s datagram_n -DTEST prot.x 

To create the server-side stubs for thetransport indicated by net i d tcp, use 

$ rpegen -n tcp -o prot_svc.c prot.x 

SEEALSO 

cc(l). 

rsh 

rsh— Remote shell 
SYNOPSIS 

rsh [ -Kdnx] [ - k r e a I m ] [ -1 user nane ] h o s t command 

DESCRIPTION 

rsh executes command On host. 
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rsh copie its standard input to the remote command, the standard output of the remote command to its standard output, 
and the standard errar of the remote command to its standard errar. Interrupt, quit, and termi nate signals are propagated to 
the remote command; rsh normally termi nates when the remote command does. T he options are asfollows: 

-K Turnsoff ali Kerberosauthentication. 

-d Using setsockopt(2), turnson socket debugging on theTCP socketsused for communication with the remote 
host. 

-k Causes rsh to obtain ti ckets for the remote host in reaim instead of the remote host's realm as determi ned by 

krb_realmof host(3). 

-ì By default, the remoteusernameisthesameasthe locai username. The -1 option allows the remote nameto be 
specified. Kerberosauthentication isused, and authorization isdetermined asin riogin(l). 

-n The -noption redi rects input from the special device. (Seethe"Bugs" section of thismanual page.) 

-x The -x option turnson D ES encryption for ali data exchange. Thismay introduce a significant delay in response 
ti me. 

If no command is specified, you will belogged in on the remote host using riogin(l). 

Shell metacharactersthatarenot quoted areinterpreted on locai machine, whilequoted metacharactersareinterpreted on 
the remote machine. Forexample, the command: 

rsh otherhost cat remotefile » localfìle 

appends the remote file remotef ile to the locai fileiocaitne, while 

rsh otherhost cat remotefile » other remotefile 
appends remotefile tO other remotefile. 

FILES 

/etc/hosts 

SEEALSO 

rlogin(l), kerberos(3), krb sendauth(3), krb_realmof host(3) 

HI STORY 

The rsh command appeared in BSD 4.2. 
BUGS 

If you are using csh(l) and put a rsh in the background without redi recti ng its input away from the terminal, itwill block 
even if no reads are posted by the remote command. If no input is desi red you should redi rect the input of rsh to using the 
-n option. 

You cannot run an interacti ve command (rogue(6) or vi(l), forexample) using rsh; usenogin(l) instead. 

Stop signals stop the locai rsh processonly; this isarguably wrong, but currently hard to fix for reasons too complicated to 
explain here. 

BSD 4.2, 24 July 1991 

rstart 

rstart— A sample implementation of a Remote Start client 
SYNOPSIS 

rstart [ - c c o n t ext ] [ - g] [ -1 u s er n a me ] [ - v] h ost name c o mma nd a r gs ... 



Parti: U ser Commands 



D ESC RIFIO N 

rstart isa simple implementation of a Remote Start client asdefined in "A Flexible Remote Execution Protocol Based on 
rsh." It uses rsh as itsunderlying remote execution mechanism. 

OPTIONS 

-ccontext This option specifies the c o nt e xt in which thecommand isto berun. A cont ext specifies a general 

environment the program isto berun in. The detai Is of this environment are host-specific; the intent is 
that the client need not know how the environment must beconfigured. If omitted, thecontext defaultsto 
x. Thisshould besuitablefor runningx programsfrom the host's "usuai" x instai lation. 

-g Interpretscommand asagenericcommand, asdiscussed in the protocol document. Thisisintended to allow 

common applicationsto beinvoked without knowing whatthey arecalled on the remote system. 
Currently, theonly generic commands defined areTerminai, LoadMonitor, i_istcontexts,and 

ListGenericCommands. 

-ì user na me Thisoption ispassed to theunderlying rsh; it requests that thecommand berun asthespecified user. 

-v Thisoption requests that rstart be verbose in itsoperation. Without thisoption, rstart di scards output 

from theremote's rstart helper, and directs the rstart helper to detach the program from the rsh 
connection used to start it. W ith thisoption, responsesfrom the helper aredisplayed and theresulting 
program isnotdetached from the connection. 



NOTES 

Thisisatrivial implementation. Far more sophisticated implementationsarepossibleand should bedeveloped. 

Error-handling isnonexistent. W ithout -v, errar reportsfrom the remote are di scarded silently. With -v, errar reportsare 
displayed. 

The$DisPLAYenvironmentvariableispassed. If it starts with acolon, thelocal hostnameisprepended. The locai domain 
nameshould beappended to unqualified hostnames, but isn't. 

T he $session_manager envi ronment variable should bepassed, but isn't. 

xn authority information ispassed for the current display. 

ice authority information should bepassed, but isn't. It isn't compi etely clear how rstart should selectwhat ICE authority 
information to pass. 

Even without -v, thesample rstart helperwill leave a shel I waiting for the program to complete. This causes no real harm 
and consumes relati vely few resources, but if it isundesirableit can beavoided by explicitly specifying the exec command to 

theshell, forexample, 0 rstart somehost exec xterm. 

Thisisobviously dependent on thecommand interpreter bei ng used on the remote system; theexamplegiven will work for 
theBourneand C shel Is. 

SEEALSO 

rstartd(l), rsh(l), "A Flexible Remote Execution Protocol Based on rsh" 
AUTHOR 

Jordan Brown, Quarterdeck Office Systems 

X Versi on 11 Release 6 
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rstartd— A sample i mplementation of a Remote Start rsh helper 
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SYNOPSIS 

rstartd 

rstartd. real [-c configfilena me ] 

D ESC RIFIO N 

rstartd isan implementation of a Remote Start "heiper" asdefined in "A Flexible Remote Execution Protocol Based 

On rsh." 

Thisdocument describes the peculiaritiesof rstartd and how it is confi gured. 
OPTIONS 

-c conf i gf m ename Thisoption specifiesthe giobai confi guration filethat rstartd isto read. N ormally, rstartd isa 
shell seri pt that invokes rstartd. reaiwith the -c switch, allowing locai configuration of the 
location of the configuration file. If rstartd. reai isstarted without the -c option, it reads 
<xRoot>/iib/xn/rstart/config, where<xRoot> refersto theroot of theXll instali tree. 

INSTALLATICI 

It is criticai to successful interoperation of the Remote Start protocol that rstartd be instai led in a directory that is in the 
default search path, so that default rsh requestsand theiik will beableto find it. 

CONFIGURATION ANDO PERATION 

rstartd is by design highly configurable. Onewould likethings like configuration file locati onsto befixed, so that users and 
administratorscan find them without searching, but reali ty isthat no two vendors will agreeon wherethingsshould go, and 
nobody thinks the originai location is'Yight." Thus, rstartd allows the relocation of ali of itsfilesand directories. 

rstartd has a hierarchy of configuration filesthat areexecuted in order when a request ismade. They areglobal config, per- 
user ("locai") config, global per-context config, per-user ("locai") per-context config, config from request. 

Asyou might guessfrom the presenceof config from request, ali of the config fi les are in the format of an rstart request. 
rstartd definesafew additional keywordswith theiNTERNAL- prefixfor specifying its configuration. 

rstartd starts by reading and executing the global config file. T hi s fi le will normally specify the locati onsof the other 
configuration filesand any system-widedefaults. 

rstartd will then read theuser's locai config file default namesHOME/. rstart. 
rstartd will then start interpreti ng the request. 

Presumably, oneof the first linesin the request will beacoNTEXT line. Thecontext nameisconverted to lowercase. 
rstartd will read the global config fi le for that context, default name<xRoot>/iib/xn /rstart /context s/<name>, if any. 
It wi II then read theuser's config fi le for that context, default name $home/ . rstart . context s/<name>, if any. 
(If neitherof theseexists, rstartd abortswith aFailuremessage.) 

rstartd will finish interpreting the request, and execute the program specified. This allows the system administrator and the 
user a largedegreeof control over the operation of rstartd. The administrator has final say, because the global config fi le 
doesn't need to specify a per-user config file. If it does, however, the user can overrideanythingfrom the global file, and can 
even completely replace the global context config files. 

The config fileshaveasomewhat more flexible format than requestsdo; they are ali owed to contain blank linesand lines 
beginningwith # are commentsand ignored. (#s in the middle of lines are data, not comment markers.) 
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Any commands run areprovided a few useful piecesof information in environment variables. Theexact namesare 
configurable, but the supplied defaults are 

$rstart_context The name of the context 

$rstart_global_contexts T he global contexts di rectory 

$rstart_local_contexts Thelocal contexts di rectory 

$rstart_global_commands Theglobal generic commands directory 

$rstart_local_commands The locai generic commands di rectory 

$rstart_{global,local}_contexts should contain one special file, §ost, which contains a list of the contexts in that 
directory in theformat specified for Listcontexts. The supplied version of Listcontexts will cat both theglobal and locai 
copiesof ©List. 

Generic commands are searched for in several places: (defaults) 

Per-user per-context directory $home/, rstart. commands /<context> 

Global per-COntext directory <XRoot>/lib/X11/ rstart /commands/<context> 

Per-user al l-contexts di rectory $home /, rstart . commands 

Global al l-COntextS directory (<XRoot>/lib/X11 /rstart/commands) 

(Yes, thismeansyou can't havean all-contexts generic command with the same name as a context. It didn't seem likeabig 
deal.) 

Each of th ese d i recto ri es should haveafilecalled @i_ist that givesthenamesand descriptionsof the commands in that 
directory in theformat specified for ListGenericcommands. 

CO NFIGU RATIO N KEYWORDS 

There are several special rstart keywordsdefined for rstartd configurati on. U nlessotherwise specified, thereareno 
defaults; related featuresaredisabled in thiscase. 

mternai-Registries n a me . . .— G ives a space-separated I ist of misc registries that this system understands. (Registries 
other than these are accepted but generate a warning.) 

Internai -Locai -Default relatìve_f ilename— G ives the name ($HOME relative) Of the per-USer COnfigfile. 

internal -global -contexts absoiute_directory_name— G i ves the name of the system-wi de contexts di rectory. 

internal-local -contexts reiative_di recto ry_name — G i ves the name ($home relative) of the per-user contexts di rectory. 

internal -global -commands absoiute_directory_name— G ives the name of the system-wi de generi c commands di rectory. 

internal -local -commands reiative_directory_name— G i ves the name ($home relative) of the per-user generic com- 
mands directory. 

internal -variable-prefix pretix— G ives the prefix for the confi guration environment variables rstartd passesto its 
kids. 

INTERNAL -AUTH- PROGRAM authscheme program argv[0] argv[1 ]...— Specifies the program tO Oin tO Set up authentica- 

tion for the specified authentication scheme program argv[0] . . . gives the program to run and its arguments, in the same 
form asthe exec keyword. 

internal -auth -input authscheme— Specifi es the data to begiven to theauthorization program as its standard input. Each 
argument ispassed as a single line. $n, wheren isanumber, isreplaced bythenth argumentto the auth authscheme argi 

arg2 . . . line. 

internal -print arbitrary text— Prints its arguments as a D ebug message. M ostly for rstartd debugging, but could be 
used to debug config fi les. 
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NOTES 

When usingtheC shdl, orany other shell that runs a script every ti me the shell is started, the script may berun several 
times. In theworst case, the script may berun threetimes: By rsh, to run rstartd; by rstartd, to run the specified 
command; by thecommand, such as xterm. 

rstartd currently limits lines, both from configfilesand requests, to bufsiz bytes. 

detach isimplemented by redi recti ng file descri ptorso, 1, and 2 to /dev/nuii and forking before executi ng the program. 
cmd isimplemented by invoking$sHEi_i_ (default /bin/sh) with -c and the specified command asarguments. 
posix-umask isimplemented in theobviousway. 

Theauthorization programsarerun in the samecontext as the target program— sameenvironment variables, path, and so 
on. Longterm, this might bea problem. 

In thex COntext, GENERIC-CMD Terminal runs xterm. In theOpenWindows COntext, GENERIC-CMD Terminal runScmdtool. 

In thex context, generic-cmd LoadMonitor runsxioad. In theopenwindows context, generic-cmd LoadMonitor runs 

perf meter. 

generic-cmd Listcontexts lists the contents of @List in both thesystem-wideand per-user contexts di rectories. Itis 
availablein ali contexts. 

generic-cmd ListGenericcommands lists the contents of ©List in the system-wide and per-user commandsdirectories, 
including the per-context subdi rectories for thecurrent context. It is availablein ali contexts 

context None isnot implemented. 

context Defauit isreally dull. 

For instali ation ease, the contexts directory in the distri bution containsafile@Aiiases, which lists a context nameand 
aliases for that context. This file isused to make symlinksin thecontexts and commandsdirectories. 

Ali misc valuesarepassed unmodified asenvironmentvariables. 

You can mistreat rstartd in any number of ways, resulti ng in anythingfrom stupì d behavior to coredumps. Other than by 
explicitly running programs, I don'tthink it can writeor delete any fi les, but there's no guaranteeof that. The important 
thing isthat (a) it probably won't do anything REALLY stupid and (b) it runs with theuser's permissions, so it can't do 
anything catastrophic. 

©List fi les need not be complete; contexts or commands that are dull or which need notor should not beadvertised need 
not belisted. In parti cular, per-user @i_ist fi les should not list things that are in thesystem-wide@List fi les. In the future, 
perhaps Listcontexts and ListGenericcommands will automati cai ly suppress lines from the system-wide files when thereare 
per-user replacements for those lines. 

Error-handling isOK to weak. In parti cular, no attempt ismadeto properly report errorson theexec itself. (Perversely, exec 
errorscould bereliably reported when detaching, but not when passingthestdin/out socketto theapp.) 

If compiled with -dodti_display_hack, rstartd will work around a bug in sco odt version 1. (1.1?) (The bug isthat thex 
clientsareall compiled with a bad library that doesn't know how to look hostnamesup using D N S. Thefix isto look up a 
hostnamein $display and substitutean ip address.) Thisisatrivial exampleof an incompatibility that rstart can hide. 

SEEALSO 

rstart(l), rsh(l), "A Flexible Remote Execution Protocol Based on rsh" 
AUTHOR 

Jordan Brown, Quarterdeck Office Systems 

X Version 11 Re!ease6 
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rup 

rup— Remote status display 
SYNOPSIS 

rup [-dhlt] [ho s t ...] 

D ESC RIFIO N 

rup displays a summary of the current system status of a parti cular host or ali hosts on the locai network. T he output shows 
thecurrent timeof day, how long the system has been up, and theload averages. Theload averagenumbersgivethenumber 
of jobsin therun queue averaged over 1, 5 and 15 minutes. 

T he followi ng opti ons are available: 

-d Foreach host, report what its locai timeis. Thisisuseful for checkingtimesynchronization on a network. 
- h Sort the di splay al phabeti cai ly by hostname. 
-ì Sort the display by load average. 
-t Sort the display by up time. 

Therpc.rstatd(8) daemon must berunningon the remote host for thiscommandtowork. rupusesan RPC protocol 

defined in /usr/include/rpcsvc/rstat.x. 

EXAMPLE 

example% rup otherhost 

otherhost up 6 days, 16:45, load average: 0.20, 0.23, 0.18 
example% 

DIAGNOSTICS 

rup: rpc: Program not registered— The rpc . rstatd(8) daemon has not been started on the remote host. 

rup: rpc : Timed out— A communication errar occurred. E ither the network is excessi vely congested, or the 
rpc.rstatd(8) daemon hasterminated on the remote host. 

rup: RPC: Port mapper failure - RPC: Timed out— T he remote host isnot Oinni ng the portmapper (see portmap(8) 

man page), and cannot accommodateany RPC-based servi ces. The host may bedown. 
SEEALSO 

ruptime(l), portmap(8), rpc. rstatd(8) 

HISTORY 

Therupcommand appeared in SunOS. 

BSD 4.3, 7 Junel993 

rusers 

rusers— Output who islogged in to machineson locai network 
SYNOPSIS 

rusers [ -al] [host . . . ] 

DESCRIPTION 

The rusers command produces output similar to who, but for the list of hosts or ali machineson the locai network. For each 
host responding to the rusers query, the hostname with thenamesof theuserscurrently logged on isprinted on each line. 
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Therusers command will waitforone minute to catch late responders. 
T he followi ng opti ons are available: 

-a Print ali machines responding even if no oneiscurrently logged in. 

-ì Print a long format listing. Thisincludestheusername, hostname, tty that the user is logged in to, the date and 
ti me the user logged in, the amountof ti mesi nce the user typed on thekeyboard, and the remote host the user 
logged in from (if appi icable). 

DIAGNOSTICS 

rusers: rpc: Program not registered— The rpc. rusersd(8) daemon has not been started on the remote host. 

rusers: rpc: Timed out— A communication errar occurred. E ither the network is excessi vely congested, or the 
rpc.rusersd(8) daemon hasterminated on the remote host. 

rusers: rpc: Port mapper faiiure - rpc : Timed out— The remote host is not runni ng the portmapper (see 
portmap(8) for more information), and cannotaccommodateany RPC-based servi ces. The host may bedown. 

SEEALSO 

rwho(l), users(l), who(l), portmap(8), rpc. rusersd(8) 

HI STORY 

Therusers command appeared in SunOS. 
BUGS 

The sorti ng optionsarenot implemented. 

BSD 4.2, 23 Aprii 1991 

rwall 

rwaii— Send a messageto users logged on a host 
SYNOPSIS 

rwall host 

D ESC RIFIO N 

The rwaii command sends a messageto the users logged in to thespecified host. The messageto besent can be typed in and 
terminated with EOForitcan bein afile. 

DIAGNOSTICS 

rwaii: rpc: Program not registered— T he rpc . rwaiid(8) daemon has not been started on the remote host. 

rwaii: rpc: Timed out— A communication errar occurred. E ither the network is excessively congested, or the 
rpc.rwaiid(8) daemon hasterminated on the remote host. 

rwaii: rpc: Port mapper faiiure - rpc: Timed out— T he remote host is not runni ng the portmapper, and cannot 
accommodateany RPC-based services. The host may bedown. 

SEEALSO 

wall(l), portmap(8), rpc. rwalld(8) 

HI STORY 

The rwaii command appeared in SunOS. 

BSD 4.2, 23 Aprii 1991 
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rwho 

rwho— Output who islogged in on locai machines 
SYNOPSIS 

rwho -a 

D ESC RIFIO N 

The rwho command produces output si mi larto who, but forali machines on the locai network. If no report hasbeen received 
from a machinefor 11 minutes, then rwho assumesthemachineisdown, and doesnot report users last known to belogged 
in to that machine. 

If a user hasn'ttyped to the system fora minute or more then rwho reports this idletime. If a user hasn'ttyped to the system 
for an houror more, then the user wi II beomitted from the output of rwho unlessthe -aflag isgiven. 

FILES 

/var/rwho/whod.* Information about other machines 
SEEALSO 

f inger(l), rup(l), ruptime(l), rusers(l), who(l), rwhod(8) 

HI STORY 

The rwho command appeared in BSD 4.3. 
BUGS 

Thisisunwieldy when thenumber of machines on the locai net islarge. 

BSD 4.2, 23 Aprii 1991 

script 

script— M aketypescript of terminal session 
SYNOPSIS 

script [ -a] [file] 

D ESC RIFIO N 

script makesatypescript of everything printed on your terminal. It isuseful for studentswho need a hardcopy record of an 
interacti ve session as proof of an assignment, as the typescript file can be printed outlaterwith ipr(l). 

If the argument fi le isgiven, script savesall dialoguein file. If no fi lename isgiven, the typescript issaved in the file 
typescript. 

Option: 

-a Appendtheoutputtofileor typescript, retai ni ng the priorcontents 

The script endswhen theforked shell exits (a control -d to exit the Bourneshell, sn(l), and exit, logout, or control -d (if 

ignoreeof isnotset) for the C -Shell, csh(l)). 

Certain interactive commands, such asvi(l), create garbage i n the typescript fi le. Script works best with commands that do 
not manipulate the screen; the results are meant to emulate a hardcopy termi nal. 




ENVIRO NMENT 

T hefollowing environment vari able is utilized by script: 

shell If the variable shell exists, the shel I forked by script will bethat shell. If shell isnot set, the Bourne shell is 
assumed. (M ostshells set this variable automatically.) 

SEEALSO 

csh(l) (forthe history mechanism) 

HI STORY 

The script command appeared in BSD 3.0. 
BUGS 

script places everything in the log file, including linefeedsand backspaces. This isnot what the naive user expects. 

BSD 4, 27 July 1991 

sed 

sed— Stream-oriented editor 
SYNOPSIS 

sei [ - hnV ] [ - e script ][-~F script-file ] [ - -help ] [ - -quiet ] [ - -silent ] 
[- -version] [- -expression=s c r i pt ] [ - -f±le=s cri pt - f i I e ][file ... ] 

DESCRIPTION 

sed readsthespecified fi les or the standard input if no files are specified, makes editing changes accordi ngto a list of 
commands, and writestheresultsto the standard output. 

0PTI0NS 

-h, --heip Print a usagemessageon standard output and exit successfully. 

-n, --quiet, --siient Suppress the default output, sed only displays li nes explicitly specified for 

output with thep command or the p flag of thes command. The default 

behavior isto echo each li ne of input, after edits, to the standard output, 
-v, - - version P ri nt the version number on the standard output and exit successfully. 

-e script, -■ expr essi on=scr i pt Append oneor more commands specified i n the stri ng seri p t to the list of 

commands If there i s just one -e option and no -f options, the -e flag may 

beomitted. 

-t scr i pt - f i i e, --fi i e=scri pt-fi i e Append the editing commands from script-fiieto the list of commands. 

M ultiple - e and -f commands may be specified. Scripts are added to the list of commands to execute in the order specified, 
regardlessof their ori gin. 

USAGE 

OPERATION 

sed operates asfollows: 

Each lineof input, not including itsterminating newlinecharacter, issuccessively copied into a pattern space(a 
tempo rary buffer). 

Ali editing commands whoseaddresses match that pattern space are seguenti al ly applied to thepattern space. 
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When reachingtheend of thecommand list, the pattern space iswritten to the standard output (except under -n) with 
an appended newline. 

The pattern space iscleared and the processi srepeated for each line in the input. 
With sed, originai input fi les remai n unchanged because editing commands only modify a copy of the input. 
Somesed commands use a hold space to saveall or part of the pattern space for later retri eval. 

COMMAND SYNTAX 

A sed script consistsof commandswith the general form: 

[a d d r es s [, addr es s ] ] [ ! ]c omma nd [a r gu ment s ] 

Typically, thereisonly onecommand per line, but commands mayalso beconcatenated on a single line by semicolons. 
Whitespacecharacters may beinserted before the first address and thecommand portionsof the script command. 

ADDRESSES 

A sed command, asindicated, can specify zero, one, ortwo addresses. An address can be 

A line number, represented in decimai. The internai linenumber count maintained by sed is cumulative across input 
filesand isnot reset for each input file 

A pattern that isa regular expression, represented by ne patterne, wherec isany character except backslash (\) or 
newline. In the address nxabcnxdefx, thesecond x standsfor itself, so the regular expression isabcxdef. H owever, the 
preferred (and equivalenti method to construct a regular expression isto enclose the pattern in slashes— /pattern/. 
Additi onally, \n can beused to match any newlinein the pattern space, except for the final newline character. 

A $ character that addresses the last lineof input. 

GNU sed also implementsa new type of address. The address hasform n ~m, which matchesany linewheretheline 
number modulo m isequal to n modulo m. If m is 0 or missing, then 1 isused in i ts place. Thisfeature isnot specified by 
POSIX. 

Thefollowing rulesapply to addressed commands: 

A command I i ne with no address sei ects each input line. 

A command linewith one address selects any line matching the address. Several commands accept only one address: =, a, 
i, r,and q. 

A command linewith two comma-separated addresses selects the first matching line and ali following linesup to and 
including the line matching thesecond address. If thesecond address starts before or is the same li ne as thefi rst address, 
then only the fi rst line is selected. 

An address followed by : selects ali linesthat do not match the address. 

REGULAR EXPRESSION S 

Regular expressionsarepatternsused in selecting text. For example, the sed command 

/stri n g / p 

printsall I i nes contai ni ng s t r i ng. 

In additi on to specifying stri ng literals, regular expressi ons can represent classesof strings. Stri ngsthus represented are sai d to 
bematched bythecorresponding regular expression. If it is possi ble for a regular expression to match several strings in a line, 
then the leftmost longest match is the one selected. 

Thefollowing symbols are used in constructingsearcn patterns: 

The nuli regular expression is equivalent to the last regular expression used. 
c Any character c not listed here— including {,},,,<, >, |, and +— match es itself. 

\c Any backslash-escaped character c , except for {, }, ,,<,>, | , and +, matches itself. 

1 -m 1 . M atches any single character except newline. 
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[ c h a r - ci ass] M atches any single character, otherthan newline, in c h a r - ci ass.To includea ] indiar- 

ci ass, it must be the first character. A rangeof characters may bespecified by separati ng the 
end characters of therangewith a -, forexample, a-z specifies the lowercase characters. The 
following I iterai expressi onscan also beused in char ■ ci ass to specify sets of characters: 

[:alnum:] [:cntrl:] [:lower-:] [:space:] 
[:alpha:] [:digit:] [:print:] [:upper:] 
[:blank:] [:graph:] [:punct:] [:xdigit:] 

If - appearsas the first or last character of char - ci ass, then it matches itself. Ali other 
characters in char - ci ass match themselves. 
[ "char ■ ci ass ] M atchesany single character, otherthan newline, not in char ■ ci ass . char - ci ass isdefined 

asin the precedi ng entry. 

If " isthefirst character of a regular expression, then itanchorstheregularexpression tothe 

beginning of a line. Otherwise, it matches itself. 
$ If $ i s the last character of a regular expression, itanchorstheregularexpression to the end 

ofaline Otherwise, it matches itself. 
\<, \> Anchorsthesingle-character regular expression orsubexpression immediately following itto 

the beginning (\<) or ending ( \>)of a word, that is, in ASCII, a maximal stringof 

alphanumeric characters, including the underscore (_). 
\(re\) Definesa (possi bly nuli) subexpression re. Subexpressionsmay benested. A subsequent 

back referenceof theform 1 \n ', wheren isa number in therangel-9, expandsto thetext 

matched bythenth subexpression. Forexample, the regular expression \(a.c\)\i matches 

thestring 'abcabc 1 , but not 'abcadc 1 . Subexpressionsareordered relative to their left 

del imi ter. 

M atchesthesingle-character regular expression orsubexpression immediately preceding it 
zero ormoretimes. If * isthefirst character of a regular expression orsubexpression, then it 
matches itself. The* operator sometimesyieldsunexpected results. Forexample, the regular 
expression b* matchesthe beginning of thestring 'abbb 1 (asopposed to thesubstring 
'bbb 1 ) becausea nuli match istheonly leftmost match. 
\+ M atches the si ngle character regular expression orsubexpression immediately preceding it 

oneor moretimes. 

\| M atches the regular expression orsubexpression specified before or after it. 

\{n ,m\} or \{n , \> or \{n \} M atches the single-character regular expression orsubexpression immediately preceding it at 

least n and at most m times. If m isomitted, then it matches at least n times. If the comma is 

also omitted, then it matches exactly n times. 
(\group\) M atches the enclosed group of regular expressions. 

Thefollowing characters only have special meaningwhen used in replacement patterns: 
\ E scape the following character. 

\n M atches the nth pattern previously saved by n ( 1 and 1 n ), where n isa number from 0 to 9. 

Previ ously saved patterns are counted from the leftmost position on the li ne. 
& P ri nts the enti re search pattern when used in a replacement string. 

COMMENTS 

If the first nonwhite character in a line isa #), sed treatsthat lineasacomment, and ignores it. If, however, thefirstsuch 
lineisof theform: 

#n 



sed runsasif the -n flag were specified. 
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GROUPING COMMANDS 

Braces({, >) can beusedto nest oneaddresswithin anotherorto apply multiple commands to thesameaddress: 

[address] [, address] { 
command 1 command 2 . . . 
> 

Theopening { must end a li ne and the dosi ng } must beon a lineby itself. 
COMMANDS 

The maximum number of permissive addressesfor each command isindicated in parentheses in thefollowing list. 

An argument denoted text consistsof oneor morelinesof text. If text islonger than onelinein length, then any newline 
characters must be hidden by precedi ng them with a backslash (\). 

An argument denoted read-fiiename orwrite-fiiename must terminate the command lineand must bepreceded by 
exactly one space. Each wnte-fiiename iscreated before processing begins. 

(0) An empty command isignored. 

(0) #comment T he line is a comment and isignored by sed. If, however, the first such line in a script isof 

theform #n, then sed behaves as if the - n f lag had been specified. 

(0) : label Affixiabei to a li ne i n the script for a transfer of control by b or t commands. 

(1) = Writethecurrent linenumberon thestandard output asa line 

(1 )a\t ext Append text followingeach linematched by the address on thestandard output before 

reading the next input line. 

(2) b label U ncondi ti onal ly transfer control to the : command hearing the i abei . Ifnoi abe is 

specified, then branchi to the end of the script; no more commands are executed on the 
current pattern space. 

(2) c\t ext Change the pattern space by replaci ng the selected pattern with t ext . W hen multiple lines 

are specified, ali lines in the pattern space are replaced with a single copy of t ext . The end 
result isthat the pattern space isdeleted and no further editing commands can beapplied 
to it. 

(2) d Delete the pattern space, preventi ng the line from bei ng passed to thestandard output, and 

start thenextcycle. 

(2) d Delete the ini ti al segment of the pattern space through the first newline and start the next 

cycle. 

(2) g Replacethecontentsof thepattern space by the contentsof the hold space. 

(2) g Append a newlinecharacter followed by the contentsof the hold space to thepattern space. 

(2) h Replacethecontentsof thehold space by the contentsof thepattern space. 

(2) h Append a newlinecharacter followed by the contentsof thepattern spaceto the hold space. 

(1) i\text I nsertt e xt bywritingit to the standard output. 

(2) ì Write the pattern spaceto standard output in a visual ly unambiguousform. N onprinting 

characters are displayed as either three-digit octal values, preceded bya\, orasoneof the 

following character Constant escape sequences: 

\\ Backslash 

\a Alert 

\b Backspace 

\t Form-feed 

\n Newline 

\r Carriage-return 

\t Tab 

w V erti cai tab 
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Long lines are folded, with thepoint of folding indicateci by a backslash (\) and a newline 
character. Theend of every lineismarked with a$. 
(2) n Copy the pattern space to the standard output. Replace the pattern space with thenext line 

of input. 

(2) n Append thenext lineof input to the pattern space with an embedded newline. (Thecurrent 

linenumber changes.) 
(2) p Print the pattern spaceto thestandard output. 

(2) p Copy theinitial segmentof the pattern spacethrough thefirst newlineto thestandard 

output. 

(1 ) q Quit by tran sferri ng control to theend of the script and do not start a new cycle. The 

pattern space is stili written to thestandard output. 
(2) r r e a d - fi i ename Read the contents of r e a d • f i ename. Placethem on the output before reading the next 

input line. 

(2) s/regul arexpressi on/ Substitute the r e pi acement String for instances Of the r egu I ar ex p r e s s i o n in the pattern 

r e pi acement /fiags space. Any character may beused instead of /. (For afuller descri ption, see the explanati on 

of replacement patterns in the"Regular Expressions" section of thismanual page.) fiags is 
zero or more of: 

n Substitutefor just the nth OCCUrrenceof the regular expression. 

g Globally substitutefor ali nonoverlapping instances of the reguiar expression 
rather than just the fi rst one. 

p Print the pattern space if a replacement wasmade. 
w wr i t e - f i i ename Append the pattern spaceto wr i t e-f i i ename if a replacement was made. 

(2) t label Branchtothe: command bearingthei abei if any substitutionshavebeen madesincethe 

most recent reading of an input li ne or execution of at. If i abei isempty, branch to the 

end of the script. 

(2) w wr i t e - f i I en a me Append the pattern Spaceto wr i t e - f i I e name . 

(2) x Exchangethe contents of thepattern and hold spaces. 

(2) y/st ri ngi /st ri n g 2 / Replaceall occurrences of characters in st r i ngi with thecorresponding character in 

stri ng2.Thelengthsofstri ngi and s t ri ng2 must be equal. Any character other than 1 1 
or newlinecan beused instead of slash to deli mit the stri ngs. W ithi n s t r i n g 1 and stri n g 2 , 
the del imiter itself can beused asa literal character if it ispreceded by a backslash. 

DIAGNOSTICS 

command oniy uses one address— A command that takes one address had two addresses specified. 
command doesn'ttake any addresses— A command that takes no addresses had an address specified. 
Extra characters after command— A command had extra text after the end. 

unexpected End -of -file— T he end of a script was reached before it should havebeen. This usuai ly occurswhen a 
command is started, but not finished. 

no previous reguiar expression— A metacharacter calli ng for a previous regular expression before any regular 
expressions wereused. 

Missing command— An address was not followed by acommand. 
unknown command— A command was not one of the ones recognized bysed. 
unexpected 1 , ' — A command had a spurious comma after an address. 
Multiple 1 ! s- M ore than one ! (exclamation point) wasused in acommand. 
unexpected g— A g character was given in a command without a precedi ng f. 
unexpected f— An f character was given in a command without a following g. 

} doesn't want any addresses— } Should be alone On a line 
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: doesn't want any addresses— The : command should not be preceded by an address. 

unterminated s command— T he replacement field of the s command should be completed with a / character. 

Multiple p options to s command — T he p option was given morethan once in an s command. 

Multiple g options to s command— Theg option wasgiven morethan oncein an s command. 

Multiple number options to s command— M orethan one number option wasgiven to an s command. 

unknown option to s— An unknown option wasused forthes command. M aybeyou shouldn't do that. 

strings tor y command are difterent ìengths— T here should be a one-to-one mapping between strings for they 
command. 

Missing 1 1 before fiiename— Therewasno spacebetween an r, w, or s///w command, and thefilenamespecified for 
that command. 

Hopelessly evil compiled in limit on number- of open file, re-compile sed .— An attempt was made tO Open 

too many files, no matter how you look at it. 
SEEALSO 

awk(l), ed(l), grep(l), perl(l), regex(3) 

HISTORY 

A sed command appeared in version 7 AT&T U N IX. 
STANDARD S 

GNU sed isexpected to bea supersetof the IEEE Stdl003.2 (POSIX) specification. 
CAVEATS 

GNU sed uses the POSIX basic regular expressi on syntax. Accordi ng to the standard, the meaningof some escape sequences 
isundefined in this syntax; notably \ j and \+. 

Asin ali GN U programsthat use POSIX basic regular expressions, sed interpretsthese escape sequences asmetacharacters. 
So, x\+ matchesoneor moreoccurrencesof x. abc\ |def matcheseither abc ordef. 

This syntax may cause problemswhen running seri ptswritten for other versi onsof sed. Some sed programs havebeen 
written with theassumption that \ ; and \+ match theliteral characters | and +. Such seri pts must bemodified by removi ng 
thespurious backslashes if they areto beusedwith GNU sed. 

BUGS 

It haslong been noted thatGN U sed ismuch slower than other implementations. Thecurrent botti eneck istheway sed 
readsand writes data files. It should read large blocks at a time (or even map files, wherethat issupported). When possi ble, it 
should avoid copying its input from one place in memoryto another. Patchesto makeit do thosethings are welcome! 

Version 2.05, December 1994 

sessreg 

sessreg— M anageutmp/wtmp entri esfor non-init clients 
SYNOPSIS 

sessreg [ - w wt mp- f i ! e ] [ - u u t mp -file] [ -1 I i ne- n a me ] [ -h h o s t • name ] 
[ -s s I ot ■ number ] [ -x Xs e r v e r s ■ f i I e ] [-tttys-file] [ -a] [ -d] u s e r - n a me 

D ESC RIFIO N 

sessreg is a simple program for managing utmp/wtmp entri es for xdm sessions. 




System V has a better interface to /etc/utmpthan BSD; it dynami cally allocates entries in the fi le i nstead of writingthem at 
fixed positions indexed by position in /etc/ttys. 

To manage BSD -styleutmp file, sessreg hastwo strategies. In conjunction with xdm, the -x option countsthenumber of 
linesin /etc/ttys and then addsto thatthenumber of the line in the xservers file that specifies the display. The display 
namemust bespecified asthei i ne - name usi ng the -1 option. Thissum isused asthes i ot ■ number in /etc/utmp that this 
entry will bewritten at. In the more general case, the -s option specifies the si ot ■ number directly. If forsomestrangereason 
your system uses a file other that /etc/ttys to manageinit, the -t option can direct sessreg to look elsewherefor acount 
of terminal sessions. 

Conversely, System V managerswill never need to usetheseoptions(-x, -s, and -t).To make the program easierto 
documentand explain, sessreg acceptsthe BSD -specific flags in the System V environmentand ignoresthem. 

BSD also hasahost - name fidd in theutmp fi le that doesn't exist in System V. This option i salso ignored by the System V 

version Of sessreg. 

USAGE 

In xstartup, placea cali like: 

sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 

and in xreset: 

sessreg -d -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 

OPTIONS 

- w w t mp ■ f il e 

- u u t mp -file 
- 1 li n e ■ n a me 



- h h o s t ■ n a me 
-s s I ot ■ number 



-x Xs er ver s - f i I e 

-t ttys-fi I e 

-a 
-d 

SEE ALSO 

xdm(l) 

AUTHOR 

Keith Packard, M IT X Consortium 

X Version 11 Release 6 



This specifies an alternatewtmp file, instead of /usr/adm/wtmp for BSD or /etc/wtmp for sysv. The 
special namenone disables writi ng recordsto /usr/adm/wtmp. 

This specifies an alternate utmp file instead of /etc/utmp. T he special namenone disables writing 
recordsto / etc/utmp. 

Thisdescribes the ime name of the entry. For terminal sessions, thisisthefinal pathnamesegment 
of the terminal device filmarne (for example, ttyde). For x sessions, it should probably be the locai 
display namegiven to the users sessi on (for example, :0). If noneis specified, the terminal name 
will bedetermined with ttyname(3) and stripped of leadingcomponents. 
This is set for BSD hoststo indicate that the session was initiated from a remote host. In typical 
xdmusage, this opti onsisnot used. 

Each potential session hasauniqueslot number in BSD systems; most are identified by the 
position of thei i ne - name in the /etc/ttys fi le This option overrides the default position 
determined with ttys-iot(3). Thisoption is inappropriate for use with xdm, the -xoption ismore 
useful. 

Asx sessions are one-per-display, and each display isentered in this fi le, this opti onssets the si ot - 
number to be the number of linesin thett ys- f m e plus the index into thisfile that the i i ne - name 
isfound. 

T his speci fi esan alternate filethat the -x option will useto count the number of terminal sessions 
on a host. 

This session should beadded to utmp/wtmp. 

This session should bedeleted from utmp/wtmp. -a or -d must bespecified. 
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setterm 



setterm 

SYNOPSIS 

setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 
setterm 



-Set terminal attributes 

-term t er mi n a I name ] 
-reset ] 
-initialize ] 
-cursor [onjoff] ] 

-keyboard pc j Olivetti j dutch ] extended ] 

-repeat [onjoff] ] 

-appcursorkeys [onjoff] ] 

-linewrap [onjoff] ] 

-snow [onjoff] ] 

-softscroll [onjoff] ] 

-defaults ] 

-f o reground black j red j green j yellow j blue j magenta j cyan j white j default ] 
-background black j red j green j yellow j blue j magenta j cyan j white j default ] 



red j green j yellow j blue j magenta j cyan j white 
green j yellow j blue j magenta j cyan j white ] 
red green j yellow j blue j magenta j cyan j white 
green j yellow j blue j magenta j cyan j white ] 



-ulcolor blackjgreyj 
-ulcolor bright redj 
-hbcolor blackjgreyj 
-hbcolor bright redj 
-inversescreen [onjoff] ] 
-bold [onjoff] ] 
-half-bright [onjoff] ] 
-blink [onjoff] ] 
-reverse [onjoff] ] 
-underline [onjoff] ] 
-store ] 

-clear [ alljrest ] ] 

-tabs [tabi tab2 tab3 ... ] ] where (tabn = 1-160) 
-clrtabs [ tabi tab2 tab3 ... ] where (tabn = 1-160) 



sgitopnm 



setterm [ -regtabs [ 1-160 ]] 

sette™ [ -blank [ 0-60 ]] 

sette™ [ -dump [ 1 -NR CONS ]] 

sette™ [ -append [ 1 -NR CONS ]] 

setterm [ -file d u mp f t I e n a me ] 

setterm [ -standout [ a 1 1 r ] ] 

D ESC RIFIO N 

sette™ writesto standard output a character string that will i nvoke the specified terminal capabilities. Wherepossible, / 
etc/termcap isconsulted to fi nd the stri ng to use. Someoptions, however, do not correspond to atermcap(5) capability. In 
thiscase, if the terminal typeisminix-vc or mìnix-vcam, the string that invokes the specified capabilities on the PC M inix 
virtual console driver is output. 0 ptions that are not implemented by the terminal areignored. 

OPTIONS 

M ost options are self-explanatory. T he less obvious options are asfollows: 
-term Can beused to overridetheTERMenvironmentvariable 

-reset D isplays the terminal reset string, which typically resetstheterminal to its power on state 

-initiaiize D isplays the terminal initialization string, which typically setstheterminal's rendering options, and other 

attributesto the default values 
-default Sets the termi nal's renderi ng opti ons to the default values 
- store Stores the termi nal 's current renderi ng options as the default values 

Linux 0.98, 25 December 1992 

SEEALSO 

tput(l), stty(l), termcap(5), tty(4) 

BUGS 

Differences between theM inixand Linux versionsare not documented. 
AUTHORS 

Gordon Irlam (gordoni@cs.ua.oz.au); adaptation to Linux by Peter M acDonald; enhancementsby M i ka Liljeberg 

(lilj eber@cs .Helsinki. Fi) 

Linux 0.98, 25 December 1992 

sgitopnm 

sgitopnm— Convert an SGI imagefileto a portableanymap 
SYNOPSIS 

sgitopnm [ -verbose] [SGI f i I e ] 

D ESC RIFIO N 

Readsan SGI imagefileasinput. Producesa PGM imagefor atwo-dimensional (one-channe!) input file, and a PPM image 
for athree-dimensional (threeor morechannels) input file. 
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OPTIONS 

-verbose G ive some i riformati on about the SG I imagefile 

BUGS 

Probably 

REFERENCES 

SGI ImageFileFormatdocumentation (draft v0.95) byPaul Haeberli (paui@sgi.coin). Avai lable via f tp at 

sgi. com : graphics /SGI IMAGESPEC. 

SEEALSO 

pnm(5), pnmtosgi(l) 

AUTHOR 

Copyright® 1994 by Ingo Wilken (lngo.Wilken@informatik.uni-oldenburg.de). 

29 January 1994 



shar 



shar— Create shell archives 
SYNOPSIS 

shar [ options ] file ... 
shar -S [ options ] 

D ESC RIFIO N 

shar creates sheii archives (or shar files) that are in text format and can bemailed. Thesefilesmay beunpacked later by 
executingthem with /bin/sn. T he resulti ng archi ve issentto standard out unlessthe -o option isgiven. A widerangeof 
features prò vi de exten si ve f I exi b i I i ty in manufacturing snarsand in specifying shar "smartness." Archives may be "vanii la" or 
comprehensive. Thismanual page reflects shar version 4.0. 

OPTIONS 

Options haveaone-letter version starti ng with - ora long version starting with - -. Theexceptionsare - -heip and -- 
version, which do not have short versi ons. 0 ptionscan begiven in any order. Some options depend on each other: The - o 
option isrequired if the -ì or -l option isused. 

The -n option isrequired if the -a option isused. 

See -v in thefollowing list. 

These are the avai lable options: 

- - version Print the version numberof the program on standard output, then immedi- 

ately exit. 

- -heip Print a help summary on standard output, then immediately exit. 

-v, - -vaniiia-operation Produce vani Ila sharsthat rely only upon theexistenceof sed and echo in 

theunsharingenvironment. In addition, if test mustalso besupported if 
the -x option isused. The -v silently di sables opti ons offensi veto the 
network cop (or brown snirt), but does warn you if it is specified with -b, - 
z, -z, -p, or -m (any of which does or might requireuudecode, gzip or 
compress in the unsharing environment). 



shar 



-v, - -no-verbose 

-w, - -no-character-count 

-n name, - -archive- name=n a me 

-a, - -net-headers 



•s who@where, ■ - submitter=who(awhere 
-x, -- no - check - existing 



-X, - -query-user 
-B, - -uuencode 

-T, - -text-f iles 
-z, - -gzip 

-Z, - -compress 

-m, - -no-timestamp 
-p, - -intermix-type 

-g X, - -level-f or-gzip=X 
-b X, - -bits-per-code=X 



Verbose off. disables the i nclusion of commentsto be output when the 
archive isunpacked. 

Do N OT check with wc -c after unpack. The default isto check. 

N ameof archive to beincluded in theheader of the shar files. (Seethe - a 

switch.) 

Allows automatic generation of headers: 
Submitted by: who@where 
Archive-name: <name>/part## 

The<name> must begiven with the -n switch. If name includesa /, then / 
part isn'tused. Thus -n xyzzy produces the fol lowi ng: 

xyzzy/part01 
xyzzy/part02 

-n xyzzy/patch produces the followi ng: 

xyzzy/patch01 
xyzzy/patch02 

-n xyzzy/patchoi . produces the followi ng: 

xyzzy/patch01 .01 
xyzzy/patch01 . 02 

Thewho@wherecan beexplicitly stated with the -s switch if the default isn't 

appropriate. who@where isessentially builtas l whoami l @ , uname'. 

0 verri de automati cally determi ned submitter name. 

0 verwrite existing files without checking. If neither -xnor -x isspecified, the 
unpack will check for and notoverwriteexistingfileswhen unpackingthe 
archive (uni ess - c is passed as a parameter to the seri pt when unpacki ng). 

1 nteracti vely overwrite existing files (D o not use for shars submitted to the 
N et.) 

Treatall filesasbinary; use uuencode priorto packing. Thisincreasesthesize 
of the archive. The recipient must haveuudecode in orderto unpack. (Useof 
uuencode is not appreciated by many on the N et.) 
Treatall fi lesastext (default). 

Use gzip and uuencode on ali files priorto packing. The recipient must have 
uudecode and gzip (used with -d) in orderto unpack. (Useof uuencode and 
gzip is not appreciated by many on the Net.) 

Use compress and uuencode on ali files priorto packing. The recipient must 
haveuudecode and compress (used with -d) in orderto unpack. (Useof 
uuencode and compress isnot appreciated by many on the N et.) Option -c 
issynonymousto -z, but is being depreciated. 
Avoid generating touch commandsto restare thefilemodification dates 
when unpacking files from the archive. 

Allow positional parameter options. Theoptions -b, -t, -z, and -z may be 
embedded, and fi lesto the right of the option will beprocessed i n the 
specified mode. 

When doing compression, use -x as a parameter to gzip. The -g option 
turnson the -z option by default. 

When doing compression, use -bx as a parameter to compress. The -b option 
turns on the -z option by default. 
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-M, - -mixed - uuencode 

-P, - -no-piping 
-c, - -cut-mark 

-f, -- bas e na me 

-d XXX, - -here-delimiter=XXX 
- F, - -f orce -p r e f i x 

-o XXX - -output-pref ix=XXX 

-1 XX - -whole-size-limit=XX 
-L XX - -split-size-limit=XX 

-S -- stdin -file- list 



M ixed mode. D etermine if thefiles are text or binary and archive correctly. 

Filesfoundto be binary are uudecoded priorto packing. (U se of uuencode is 

not appreciated by many on the N et.) 

Usetemporary files instead of pipesin the shar file. 

Start the sharwith a cut line. A linesaying cut nere isplaced at the start of 

each output file. 

Restare byfilenameonly, rather than path. Thisoption causesonlyfilenames 
to beused, which isuseful when building a snar- from several d i recto ri es, or 
another directory. N otethat if a directory nameispassed to snar, the 
substructureof that directory wi II berestored whether -t isspecified or not. 
Use xxx to del imi t the files in the snar instead of shar_eof. Thisisforthose 
who wantto personalizetheir shar file. 

Forcesthepr ef i x character (normally x unlesstheparameter to the -d 
option starts with x) to beprepended to every lineeven if not required. This 
option may slightly increase the sizeof the archive, especially if -Bor -z is 
used. 

Save the archi veto files xxx .01 through xxx .nn instead of standard out. 

M ust beused when the -1 or the -l switches are used. 

Limit the output fi le size to xx k bytes, but don't split i nput fi les. 

L i mi t output file size to xx k bytes and split files if necessary. The archi ves 

created with thisoption must beunpacked in correct order. 

Read list of fi lesto be packed from the standard input rather than from the 

command line. Input must bein aform similar to that generated by the 

tind command, one filmarne per line Thisswitch is especially useful when 

thecommand linewill not hold the I ist of files to be packed. Forexample: 

find . -type f -print | sort | shar -S -Z -L50 -o /tmp/big 

If -p isspecified on thecommand line, then theoptions -b, -t, -z, and -z 
may beincluded in thestandard input (on a li ne separate from filenames). 
The maximum numberof li nesof standard input, filenames, and options 
may not exceed 1024. 



EXAMPLES 



shar 
shar 
shar 



> cprog.shar # ali C prog sources 
*.[ch] > cprog.shar # non-verbose, .c and .h files 
-128 -oarc.sh *.arc # ali binary .are files, into 



# files arc.sh.01 thru arc.sh.NN 

shar -f /lcl/src/u*.c > u.sh # use only the filenames 

WARNINGS 

No chmod or touch isever generated for di rectories created when unpacking. Thus, if a directory isgiven to shar, the 
protection and modification dates of corresponding unpacked directory may not match thoseof the originai. 

If a directory ispassed to shar, it may bescanned more than once. Therefore, oneshould becareful notto changethe 
directory while shar isrunning. 

Becareful that the output file! s) are not included in theinputsor shar may loop until the disk fili sup. Beparticularly careful 
when a directory ispassed to shar that the output fi les are not in that directory (or a subdirectory of that directory). 

Useof the -b, -z, or -z, and especially -m, may slow the archive processarsi derably, dependi ng on thenumber of files. 

Useof -x produces snarsthat will cause problems with many unshar procedures. Use this feature only for archi vesto be 
passed amongagreeable parties. Certainly, -x is not for shell archives that areto besubmitted to Usenet. Usageof -b, -z, or 
-z in N et shars will cause you to beflamed off theearth. N ot using -m or not usi ng -f may also get you occasionai 
complaints. 
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SEEALSO 

unshar(l) 

DIAGNOSTICS 

There are errar messagesfor il legai or incompatibleoptions; for nonregular, missing, or inaccessi blefiles; orfor (unlikely) 
memory allocation failure. 

AUTHORS 

shar(3) isaderived work based on theeffortsof the following: James Gosling at CM U (decvaximicrosof !uw-beave! jim), 
M ichael A. Thompson, D alhousieU niversity, H alifax, N .S., Canada, Bill Davidsen (davidsen@sixhub), Richard H . 
Gumpertz (rhg@cps.coM), Colas N ahaboo (coias@avahi.inria.fr), Bill Aten (biii@netagw.com), D ennisBoylan 
(dennis%nanovx@gatech.edu), Warren Tucker (wht%n4hgf @gatech . edu), and other anonymous persons. J an Djfrv 
(jhd@ìrfu.se) created the man pages. 

27 September 1990 

shlock 

shiock— Createlockfiles for usein shell scripts 
SYNOPSIS 

shlock -p pid -f name [ -b ][-u ][-o ] 

DESCRIPTION 

shiock tristo create a lock file named name andwritetheprocessID pi d into it. If thefile already exists, shiock will read 
theprocess ID from the fi le and test to seeif theprocess iscurrently running. If the prò cess exists, then the fi le will not be 
created. 

shiock exitswith azero status if it wasableto create the lock fi le, or non-zero if the file refersto thecurrently active process. 

Processi Dsarenormally read and written in ASCII. If the -bflag isused, then they will bewritten asa binary int. For 
compati bility with other systems, the -u flag isaccepted asa synonym for - b because bi nary locksareused by many uucp 
packages. 

Thefollowingexampleshowshow shiock would beused within a shell script: 

LOCK=/news/lib/LOCK.send 

trap 'rm -f ${LOCK} ;exit1' 1 2 3 15 

if shlock -p $$ -f ${LOCK} ; then 

# Do appropriate work 

else 

echo Locked by 'cat ${LOCK}' 
fi 

If the -cflag isused, then shiock will not create a lock file, butwill instead use the fi le to seeif the lock isheld by another 
program. If the lock isvalid, the program will exit with anon-zero status; if the lock isnotvalid (thatis, invoking shiock 
without the flag would havesucceeded), then the program will exitwith azero status. 



HI STORY 

Written by Ri eh $alz (rsaiz@uunet.uu.net) after a descri ption ofHDBUUCP locking given by Peter H oneyman. 
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showrgb 

showrgb— Uncompilean RGB colorname database 



SYNOPSIS 

showrgb [ database ] 

D ESC RIFIO N 

The showrgb program readsan RGB colorname database com pi led for use with thedbm database routines and convertsit 
back to sourceform, printing theresult to standard output. The default database is the one that x was bui It with, and may be 
overridden on thecommand line. Specify the database namewithout the .pag or .dir suffix. 

FILES 

<xRoot>/iib/xn/rgb D efault database 

X Versi on 11 Re!ease6 

shrinkf ile 

shrinkfiie— Shrink a fileon a line boundary 
SYNOPSIS 

shrinkfiie [ -s s i z e ] [ -v ] file... 

DESCRIPTION 

The shrinkfiie program shrinks fi lesto agiven size, preservi ng the data at the end of thefile Truncation isperformed on 
lineboundaries, wherea lineisaseriesof bytes ending with anewline, \n. Thereisno line length restri ction and filesmay 
contai n any binarydata. 

Temporary files arecreated in the /tmp directory. T he tmpdir environment variable may be used to specify a different 
directory. 

A newlinewill beadded to any nonempty file that does not end with a newl ine. The maximum file size wi II not beexceeded 
by thisaddition. 

By default, files are truncated to zero bytes. The -s flag may beused to change the maximum size. B ecause the program 
truncatesonly on lineboundaries, thefinal size may bemay besmaller then thespecified maximum. The size parameter 
may end with ak, m, org, indicati ng kilobyte (1024), megabyte (1048576) or gigabyte (1073741824) lengths. Uppercase 
letters arealso allowed. The maximum fi le size is 2147483647 bytes. 

If the -v flag isused, then shrinkfiie will print a status lineif afilewasshrunk. 
HISTORY 

Written by Landon Curt N oli (chongogtoad.com) and Ri eh $alz (rsaiz@uunet. uu.net) for InterN etN ews. 



sirtopnm 

sirtopnm— Convert a Soli taire fi le into a portableanymap 



SYNOPSIS 

sirtopnm [si r f ì I e ] 



size 




D ESC RIFIO N 

Reads a Solitaire I mage Recorder fi le as input. Producesaportableanymap as output. T he typeof the output filedependson 
the input file; if it'san MGI TYPE 17 file a pgm fi le is written. If it'san MGI TYPE 11 file a ppm file is written. The 
program tellsyou which typeit iswriting. 

SEEALSO 

pnmtosir(l), pnm(5) 

AUTHOR 

Copyright© 1991 by M arvin Landis. 

20 M ardi 1991 

size 

size— List section sizesand total size 
SYNOPSIS 

size [ -A -B - -format=compat i bi I i t y ][--help ] 

[ -d | -o | -x ! --radix=number ] 

[ - -target=bf d n a me ][-V ] --version ] objfile ... 

D ESC RIPTIO N 

TheGN U size utility li sts the section sizesand the total sizefor each of the object files o b j file in itsargument list. By 
default, one li ne of output isgenerated foreach object fi le or each modulein an archive. 

OPTIONS 

-A, -B, - -format compatibility 
- -help 

-d, -o, -x, - - radix n u mb e r 



- -target bf dname 
-V, - - version 

SEEALSO 

binutiis entry in info; TheGN U BinaryU tilities, Roland H . Pesch (October 1991); ar(l), objdump(l) 
COPYING 

Copyright© 1991 F ree Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual, provi ded the copyright noticeand this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof this manual under the conditionsfor verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to this one. 



Usingoneof theseoptions, you can choosewhether the output from GNU size 
resembles output from System V size (using -a, or - -format=sysv ), or Berkeley 
size (usi ng -b or - -format=berkeiey) . The default is the one-li ne format similarto 
Berkeley's. 

Show a summary of acceptable arguments and options. 
Usingoneof theseoptions, you can control whether the size of each section isgiven 
in decimai (-d, or - -radix 10); octal ( -0, or - -radix 8); or hexadecimal (-x, or 
--radix 16). In --radix number, only the three values (8, 1 0, 1 6) are supported. 
Thetotal size is always given in two radices: decimai and hexadecimal for -d or -x 
output, or octal and hexadecimal ifyou're using -o. 

You can specify a particular object-code format for obj file as b f dname . Thismay 
not be necessary; size can automati cally recognizemany formats. (Seeobjdump(l) 
for information on listingavai labi e formats.) 
D i splay version number information on size itself. 
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Permission is granted to copy and distri bute translations of this manual into another language, under the above condì ti ons 
for modified versi ons, except that this permission noticemay beincluded in translations approved by the F ree Software 
Foundation instead of in theoriginal English. 

CygnusSupport, 5 N ovember 1991 
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sidtoppm— Convert an AutoCAD sii de fi le into a portable pixmap 
SYNOPSIS 

sldtoppm [ -adjust] [ -dir] [ -height j -ysize s ] [ -info] [ -lib j -Lib na me ][ -scale s] 
[ -verbose] [ -width ] -xsize s ] [s li def il e ] 

D ESC RIFIO N 

sldtoppm readsan AutoCAD slide file and outputs a portable pixmap. If no siidefiie isspecified, input isread from 
standard input. Theppmdraw library isused to convert the vector and polygon information in the slide fi le to a pixmap; see 
the file ppmdraw. h for details on this package. 



OPTIONS 

-adjust 



-dir 



-height s i ze 



- info 



-lib name 



- Lib n a me 



-scale s 



-verbose 
-width s i z e 



-xsize s i z e 



-ysize s i z e 



If the display on which the slide file was created had nonsquare pixels, when the slide is processed with 
sldtoppm and the -adjust option isnotpresent, thefollowingwarningwill appear: warning - pixels on 
source screen were non-square. 

Specifying -adjust will correct image width to compensate. Specifying the -adjust option causes 
sidtoppm to scale the width of the image so that pixels in the resulti ng portable pixmap are square (and 
hence ci rcles appear astrue ci rcles, not el li pses). The scali ng isperformed in the vector domain, before 
scan-converting theobjects. Theresultsare, therefore, superi or in appearanceto whatyou'd obtain were 
you to perform the equi vai ent scali ng with pnmscaie after thebitmap had been created. 
The input isassumed to bean AutoCAD slide library file. A directory listing each slide in the library is 
printed on standard errar. 

Scales the image in the vector domain so it issi z e pixels in height. If no -width or - xsize option is 
specifi ed, thewidth will beadjusted to preserve the pixel aspect ratio. 

Dump the slide fi le headeron standard errar, displayingtheoriginal screen sizeand aspect ratio among 
other information. 

Extracts the slide with thegiven name from the slide library given as input. The specified name isconverted 
to uppercase. 

Extracts the slide with thegiven name from the slide library given as input. The name isused exactly as 
specified; it is not converted to uppercase. 

Scales the imagebyfactors, which may be any floating-point value greater than zero. Scaling isdone after 

aspect ratio adjustment, if any. B ecause scaling isperformed in the vector domain, before rasterization, the 

results look much betterthan running the output of sidtoppm through pnmscaie. 

D umps the siidefiie header and lists every vector and polygon in thefileon standard errar. 

Scales the image in the vector domain, so it is size pixels wide If no -height or - ysize option is 

specified, the height will beadjusted to preserve the pixel aspect ratio. 

Scales the image in the vector domain so it is s i ze pixels wide. If no -height or - ysize option isspecified, 
the height will beadjusted to preserve the pixel aspect ratio. 

Scales the image in the vector domain so it issi z e pixels in height. If no -width or - xsize option is 
specified, thewidth will beadjusted to preserve the pixel aspect ratio. 



Ali flags can be abbrevi ated to their shortest unique prefix. 



smproxy 

BUGS 

Only Level 2 slidesareconverted. Level 1 format has been obsolete si nce the advent of AutoCAD Release9 in 1987 and was 
not portable across machine archi tectures. 

Slide library itemswith names contai ni ng 8-bit (such asISO ) or 16-bit (Kanji, for example) characters may not be round 
when chosen with the -iib option unlesssidtoppm has been bui It with character set conversion functions appropriate to the 
locale. You can alwaysretrieveslidesfrom librariesregardlessof the character set by usingthe -i_ib option and specifyi ng the 
precise nameof library member. U se the - dir option to list theslidesin a library if you'reunsureof theexact name. 

SEEALSO 

AutoCAD ReferenceM anual: "Slide F i le Format"; pnmscaie(l), ppm(5) 

AUTHOR 

John Walker 
Autodesk SA 

AvenuedesChamps-M ontants 14b 
CH-2074MARIN 

Sui sse/ Sch wei z/ Svi zzerà/ Svizra/ Swi tzerl an d 

Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 
Voice 038/33 76 33 

Permission to use, copy, modify, and distri butethis software and its documentati on for any purposeand without feeis 
hereby granted, without any conditionsor restri ctions. T hi s software isprovided "asis" without express or implied warranty. 

AutoCAD and Autodesk are regi stered trademarksof Autodesk, Inc. 

10 October 1991 

smproxy 

smproxy— Session M anager Proxy 
SYNOPSIS 

smproxy [-clientld id] [-restore s a v e F i I e ] 

OPTIONS 

-ciientid id Specifies the session I D used by smproxy in the previous session. 

-restore savenie Specifies the file used by smproxy to savestatein the previous session. 

DESCRIPTION 

smproxy allowsx applications that do not support X11R6 session management to partici paté in an X11R6 session. 
In order for smproxy to actasa proxy for an x application, oneof thefollowing must betrue: 

■ The application mapsatop-level window contai ni ng the wm_client_leader property. Thisproperty provides a pointer 
to the client leader window that contai ns the wm__class, wm__name, wm_command, and wm_client_machine properties. 

or 

■ The application mapsatop-level window that does not contai n the wm_client_leader property. H owever, this top-leve! 
window contai ns the wm_class, wm_name, wm_command, and wm_client_machine properties. 
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An application that supportsthewM_sAVE_YouRSELF protocol will recei ve a wm_save_yourself client messageeach timethe 
session manager issues a checkpoint or shutdown. Thisallows the application to save state. If an application doesnot 
support thewM_sAVE_Y0URSELF protocol, then the proxy will provi de enough information to the session manager to restart 
theapplication (usi ng wm_command), but no state will berestored. 

SEEALSO 

xsm(l) 

AUTHOR 

Ralph M or, X Consortium 

X Versi on 11 Re!eas96 



sort 

sort— Sort lines of text files 
SYNOPSIS 

sort [ -cmus] [ -t separatori [-0 output-file] [-Ttempdir] [ -bdf iMnr] 
[+P0S1 [-P0S2]] [ -k POSI [ ,P0S2] ] [file...] 
sort {- -tielp, - -version} 

D ESC RIFIO N 

Thismanual page documents the GN U version of sort. sort sorts, merges, or comparesall the linesfrom thegiven files, or 
the standard input if no files are given. A filenameof - means standard input. By default, sort writestheresultsto the 
standard output. 

sort hasthreemodesof operati on: sort (the default), merge, and check for sortedness. The following opti onschange the 
operati on mode: 

-c Check whether thegiven files are al ready sorted; if they arenot ali sorted, print an errar messageand exitwith a 

status of 1 . 

-m M erge thegiven files by sortingthem asagroup. Each input file should alreadybe indi vidually sorted. Italways 
works to sort instead of merge; merging isprovided becauseit isfaster, in the case whereitworks. 

A pair of lines iscompared asfollows: if any key fields havebeen specified, sort compareseach pair of fields, in theorder 
specified on thecommand line, accordi ng to the associ ated ordering options, until adifferenceisfound orno fields are left. 

If any of theglobal options Mbdfinr are given but no key fields are specified, sort comparestheentire lines accordi ngto the 
global options. 

Finally, asa last resort when ali keys compare equal (or if no ordering options were specified at ali), sort compares the lines 
byteby byte in machine collatingsequence. The last resort comparison honorsthe -r global option. The -s (stabi e) option 
disables this last-resort comparison so that lines in which ali fields compare equal are left in their originai relative order. If no 
fields or global optionsare specified, -s hasno effect. 

GNU sort hasno limi tson input linelength or restrictionson bytesallowed within line. In addition, if the final byteof an 
input fileisnotanewline, GNU sort silently suppliesone 

If theenvironment variableTMPDiR is set, sort uses it as the directory in which to puttemporary files instead of the default, 
/tmp. The-T tempdir option isanother way to select thedirectory for temporary files; it overrides theenvironment 
variable. 

The following opti onsaffect the ordering of output lines. They may be specified globally or aspart of aspecific key field. If 
no key fields are specified, global options apply to comparison of enti re lines; otherwise, theglobal options are inherited by 
key fields that do not specify any special options of their own. 




-b Ignoreleading blankswhen findingsort keysin each line. 

-d Sort in phone directory order; ignoreall characters except letters, digits, and blankswhen sorting. 
-f Fold lowercase characters into the equivalentuppercase characters when sorting so that, forexample, b issorted 
thesameway b is. 

-i Ignore characters outsidetheASC II range 040-0176 octal (inclusive) when sorting. 

-m An initial string, consisti ngof any amount of whitespace, followed bythree letters abbrevi atinga month name, is 
folded to uppercase and compared in the order 'jan 1 < teb 1 < ... < 'dec. Invalid names compare lowto 
valid names. 

-n Compareaccordingtoarithmeticvaluean initial numeric string consisting of optional whitespace, an optional - 

sign, and zero or more digits, opti onally followed by a decimai point and zero or more digits. 
-r Reverse the result of comparison, so that lineswith greater key valuesappear earlier in the output instead of later. 

Other optionsare 

-o output-file W rite output to o ut put - f i i e instead of to the standard output. If output - f i i e isoneof the input 

files, sort copies it to a temporary file bef ore sorting and writing the output to o ut put ■ file. 

-t separator U se character s e pa r at o r as the field separator when findi ng the sort keys in each line. By default, 

fields areseparated by the empty string between a nonwhitespace character and a whitespace 
character. That i sto say, given theinput linetoo bar, sort breaksit into fields too and bar.The 
field separator isnot considered to bepart ofeither the field precedi ng or the field following it. 

-u For the default case or the -m option, only output the first of a sequence of lines that compare 

equal. Forthe -c option, check that no pairof consecutivelinescomparesequal. 

+posi [ -pos2] Specify a field within each lineto useasa sorting key. Thefield consists of the portion of theline 

starti ng at posi and up to (but not includi ng) pos2 (orto the end of the line if pos2 isnot given). 
Thefieldsand character positionsarenumbered starting with 0. 

-k posi [ ,pos2] An alternate syntaxfor specifying sorting keys. The fields and character positions are numbered 

starting with 1. 

A position hastheform t .c, wheret isthenumber of thefield to use and c isthenumber of the first character from the 
beginningof thefield (for +pos) or from the end of the previous field (for -pos).The .c part of a position may beomitted, 
in which caseit istaken to be the first character in thefield. If the -b option hasbeen given, the .c part of a field specifica- 
tion iscounted from the first nonblank character of thefield (for +pos) or from the first nonblank character following the 
previous field (for -pos). 

A +pos or - pos argument may also haveany of the option letters Mbdtinr appended to it, in which case the global ordering 
optionsare not used for that parti cular field. The -b option may beindependently attached to either or both of the+pos and 
-pos partsof a field specificati on, and if it isinherited from the global options, it will be attached to both. If a -n or -m 
option isused, thus implying a -b option, the -b option istaken to apply to both the+pos and the - pos partsof a key 
specificati on. Keys may span multiple fields. 

In addition, when GNU join isinvoked with exactly one argument, the following optionsare recognized: 
--heip Printausagemessageon standard output and exit successfully 

--version Print version information on standard output, then exit successfully 

COMPATIBILITÀ 

H istorical (BSD and System V) implementationsof sort havediffered in their interpretati on of some options, parti cularly 
-b, -f, and -n.GNU sort follows the PO 5IX behavior, which isusually (but not always) li ke the System V behavior. 
Accordi ng to POSIX, -n no longer implies -b. For con si sten cy, -m has been changed in thesameway. This may affect the 
meaning of character positions in field specificationsin obscure cases. If this bitesyou, thefix isto add an explicit -b. 

BUGS 



T he different meani ngof field numbers dependi ng on whether -k isused is confusi ng. It'sall PO SI X's fault! 

GNU TextUtilities 
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spctoppm 

spctoppm— Convert an Atari compresseci Spectrum fileinto a portablepixmap 
SYNOPSIS 

spctoppm [s pc f i I e ] 

D ESC RIFIO N 

spctoppm readsan Atari compresseci Spectrum file as input and produces a portable pixmap as output. 
SEEALSO 

sputoppm(l), ppm(5) 

AUTHOR 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 

19 July 1990 



split 



split— Split a file into pieces 
SYNOPSIS 

split [ -I i nes ] [ -1 I i n e 5 ] [ - b b y t e s [ bkm] ] [ -C b y t e s [ bkm] ] [ ■ -lines=l i nes ] 
[ - -bytes=byt es [bkm] ] [ - -line-bytes=byt es [bkm] ] [--help] [--version] 
[infile [outf ile-pref ix] ] 

D ESC RIFIO N 

Thismanual page documents the GN U version of split, split creates one or more output fi les(asmany asnecessary) 
containing consecutive sectionsoftheinfiie, or the standard input if noneisgiven orthename - isgiven. By default, 
sput putslOOO li nes of the input fi le orwhatever isleft if it islessthan that, into each output fi le. 

The output filenamesconsistof a prefixfollowed by agroup of letters, chosen so that concatenati ng the output filesin sorted 
order by fi lename produces the originai input file in order. The default output fi lenameprefix isx. If the outf ile- prefix 
argument isgiven, it isused astheoutput filmarne prefix instead. 

OPTIONS 

-i i nes, -ì i i nes, --iines=i i nes Putì i nes li nes of the input fi le into each output file. 

-b bytes [bkm], - -bytes=byt es [bkm] Put byt es bytes of the input file i nto each output file bytes isa non-zero 

integer, opti onally followed by oneof thefollowing charactersto specifya 

different unit: 

b 512-byte blocks 

k 1-kilobyte blocks 

m 1-megabyte blocks 

-c bytes [bkm], - -ime-bytes=by t e s [ bkm] Put i nto each output fi le asmany complete lines of the input file as is 

possiblewithoutexceeding bytes bytes. If alinethatislongerthan bytes 
bytes occurs, put byt es bytes of it into each output file unti I lessthan byt es 
bytes of the li ne are left, then continue normally. bytes has the sam e format 
asforthe ■ -bytes option. 



sputoppm 



Print ausagemessageand exit with a non-zero status. 
P ri nt version informati on on standard output then exit. 

GNU Text Utilities 

spottopgm 

spottopgm— ConvertSPOT satellite images to portable graymap format 
SYNTAX 

spottopgm [ - 1 1 2 1 3 ] [Firstcol Fi r s 1 1 i ne Lastcol LastMne] inputfile 

OPTIONS 

-1 ; 2 1 3 Extractthegiven color from the SPOT image Thecolorsareinfrared, visible 

light, and ultra-violet, although I don't know which correspondsto which 
number. If the image is in color, thiswill beannounced on standard error. 
The default colorisi. 

Firstcol Firstiine Lastcol Lastiine Extract the specified rectangle from the SPOT image. M ost SPOT images are 

3,000 lines long and 3,000 or morecolumnswide. U nfortunately, theSPOT 
format only givesthewidth and not the length. The width isprinted on 
standard error. The default rectangle is the width of the input image by 3,000 
lines. 

D ESC RIFI0 N 

spottopgm convertsthenamed inputfile into portable graymap format, defaultingto the first color and the whole SPOT 
image unless specified by theoptions. 

INSTALLATI0N 

You must edit the source program and either define bigendian or littleendian, and fix thetypedefs for uint32t, 
uinti6t, and uintst appropri ately. 

BUGS 

Currently, spottopgm doesn't determi ne the length of the input fi le thiswould involvetwo passes over the input file. It 
defaultsto 3,000 lines instead. 

spottopgm could extract a three-color image (ppm), but I didn't feel like making the program more compii cated than it is 
now. Besides, thereisno one-to-onecorrespondencebetween red, green, blue, and infra-red, visible, and ultra-violet. 

l'vehad only a limi ted number of SPOT images to play with, and thereforewouldn't guaranteethat thiswill work on any 
other i mages. 

AUTH0R 

W arren T OOmey (wkt@csadf a . cs . adf a . oz . au) 

SEEALS0 

Therest of thepbmpius suite. 



- - help 

- - version 



sputoppm 

sputoppm— Convert an Atari uncompressed Spectrum file into a portable pixmap 
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SYNOPSIS 

sputoppm [s puf i I e ] 

D ESC RIPTIO N 

sputoppm reads an Atari uncompressed Spectrum fileasinputand producesaportablepixmapasoutput. 
SEEALSO 

spctoppm(l), ppm(5) 

AUTHOR 

Copyright© 1991 by Sta/e Belczyk (seb3@gte.com) and Jef Poskanzer. 

19 July 1990 



sq 

sq— Squeezeasorted word list 
unsq— Unsqueezeasortedword list 

SYNOPSIS 

sq < nf i I e > o u t f i I e 
unsq < i nf i I e >outfile 

D ESC RIFIO N 

sq compressesasorted list of words {a dictionary)- Forexample, 

sort /usr/dict/words ] sq j compress > words. sq.Z 

will compress dict byaboutafactorof 4. 

unsq uncompresses the output of sq. Forexample, 

compress -d < words. sq.Z ] unsq ] sort -f -o words 

will uncompress a dictionary compressed with sq. Thesqueezing isachieved by eliminating common prefixesand replacing 
them with a single character that encodesthenumber of characters shared with the precedi ng word. Theprefix sizeis 
encoded as a single printable character: 0-9 represent 0-9, A-Z represent 10-35, and a-zrepresent 36-61. 



AUTHOR 

M ikeWexIer 

SEEALSO 

compress(l), sort(l). 

startx 

startx— I n iti al ize an xsession 
SYNOPSIS 

startx [[client ] opti o n s ..] [-- [ server ] opti ori s ... ] 



Locai 



startx 




DESCRIPTION 



NOTE 



The startx script supplì ed with the X 11 distri bution isasampledesigned moreasa basefor customization than asafin- 
ished product. Si te ad m i n i strato rs are u rgecl to customizeitfortheirsite— and to update thismanual pagewhen they do. 



The startx script is a front end to xinit that providesa somewhat nicer user i nterface f or running a single session of theX 
Window System. It istypically run with no arguments. 

To determi ne the eli entto run, startx first looksfor afilecalled .xinitre in the user's home directory. If that isnot found, 
it uses the fi le xinìt re in the xinit library directory. If command-lineclient optionsaregiven, they override this behavior. 
To determi ne the server to run, startx first looksfor afilecalled .xserverrc in the user's home directory. If that isnot 
found, it uses the fi le xserverrc in thexinit library directory. If command-l ine server optionsaregiven, they override this 
behavior. U sersrarely need to providea .xserverrc file. (Seethexinit(l) manual page for more detailson the arguments.) 

The .xinitre istypically a shell script that startsmany ci ients accordi ngto the user's preference. When thisshell script exits, 
startx kills the server and performsany other session shutdown needed. M ost of the clientsstarted by .xinitre should be 
run in the background. The last client should run in theforeground; when it exits, the session will exit. Peopleoften choosea 
session manager, window manager, orxterm as the "magic" client. 

EXAMPLE 

Following is a sample xinitre that starts several applicationsand leaves the window manager running as the "last" applica- 
tion. Assumi ng that the window manager has been configured properly, the user then chooses the Exit menu item to shut 
down x. 

xrdb -load $HOME/ .Xresources 
xsetroot -solid gray & 
xbiff -geometry -430+5 & 
oclock -geometry 75x75-0-0 & 
xload -geometry -80-0 & 
xterm -geometry +0+60 -ls & 
xterm -geometry +0-100 & 
xconsole -geometry -0+0 -fn 5x7 & 
exec twm 

EN VIRO NMENT VARIABLES 

display T h is vari abl e gets set to the nameof the display to which ci ients should connect. N ote that th i s gets set, not read. 
FILES 

$(home)/ .xinitre Client to run. Typically a shell script that runs many programs in the background. 

$(home) / .xserverrc Server to run. The default is x. 

<xRoot>/iib/xi 1/ xinit /xinit re Client to run if the user has no .xinitre file. <xRoot> refersto theroot of the X 11 

instali tree. 

<xRoot>/iib/xi 1 /xinit /xserverrc Client to run if the user has no . xserverrc file. This isonly needed if the server 

needs special arguments or isnot named. <xRoot> refersto therootof the X 11 
instali tree. 

SEEALSO 

xinit(l) 
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strings 

strìngs— Print the strings of printablecharacters in files 
SYNOPSIS 

strings [ -a J - 1 - -ali ] [ -f | - -print-f Ile-name] [ -o ][--help ] [ -v | - -version ] 
[ -n mìn-len ]-mln-len - - bytes= min-len ][-t o,x,d ] 
[ - -target=bf d na me ] |--radix= o,x,d ] file 

D ESC RIPTIO N 

Foreach file given, GNU strings printstheprintablecharacter sequencesthat areat leastfour characterslong(or the 
number given with theoptionsbelow) and arefollowed by a nul or newlinecharacter. By default, it only prints the strings 
from theinitialized data sectionsof object files; for other types of files, it prints the stri ngsfrom thewholefile. 

strìngs ismainly useful for determiningthecontentsof nontext files. 
OPTIONS 

The long and short formsof options, shown hereas alternati ves, areequivalent. 

-a, --ali, - Do notscan only theinitialized datasection of object fi les; scan thewhole 

files. 

-f, - -print -fiie-name Print the name of the file before each string. 

--heip Printasummary of the options to strings on the standard output and exit, 

-v, --version Print the version number of strings on thestandard output and exit, 

-n mi n- 1 en, ■ mi n - 1 e n , -bytes=mi n- 1 en P ri nt sequences of characters that are at least mi n- 1 en characters long, instead 

of the default 4. 

-t o,x,d, - -radix=o,x,d Print the offset withi n the fi le before each string. The single character 

argument specifies the radixof the offset— octal, hexadecimal, or decimai. 

- -target=bf dna me Specify an object code format other than your system's default format. (See 

objdump(l), for information on listing availableformats.) 

-o Like -t o. 

SEEALSO 

binutiis entry in info; TheGN U BinaryU tilities, Roland H . Pesch (October 1991); ar(l), nm(l), objdump(l), raniib(l). 
COPYING 

Copyright© 1993 F ree Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modifi ed versi onsof this manual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof this manual into another language, under the above conditions 
for modifi ed versi ons, except that this permission notice may beincluded in translationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

CygnusSupport, 25 June 1993 




strip 

strip— D iscard symbolsfrom object fi les. 
SYNOPSIS 

strip [ -Fbf d n a me ] - -target=bf d n a me ] [ -Ibfdname | 
- -input -target=bf dn a me ] [ -Obf dname ] - -output-target=bf dname ] 
[-Rsecti onname | - - remove - section^s ecti orinarne ] [ -s| --strip-ali ] 
[ -S| -g| - -strip-debug ] [ -x | - -discard-all ][-X] --discard-locals] 
[ -v | - -verbose ] [ -V| - -version ][-Vj--help ] objfile ... 

D ESC RIFIO N 

GNU strip discards ali symbolsfrom the object files obj f i i e. The list of object files may include archives. At least one 
object file must be given. 

strip modifiesthefilesnamed in itsargument, ratherthan writing modified copiesunder different names. 
OPTIONS 

-F bfdname, - - target=b f d n a me 
- - help 

-I bf dnamefdname", - - input - target=bf d n a me 

-0 bfdname, - -output -target=bf d n a me 
-R s e c t i o n n a me , - - remove -section=s e c t i o n n a me 

-s, - - strip -ali 
-S, -g, - -strip-debug 
-x, - -discard-all 
-X, - -discard-locals 

-v, - -verbose 

-V, - - version 

SEEALSO 

binutns entry in info; TheGNU BinaryU tilities, Roland H . Pesch (Octoberl991) 
COPYING 

Copyright© 1991 F ree Software Foundation, Inc. Permission isgranted to makeand distri bute verbatim copiesof this 
manual provided the copyright noti ce and this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distri bute modified versi onsof this manual under the conditionsfor verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to this one. 

Permission isgranted to copy and distri bute translati onsof this manual into another language, under the above condì ti ons 
for modified versi ons, except that this permission notice may beincluded in translationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

Cygn us Supporr., 5 N ovember 1991 



Treat theoriginal o b j f i le asafilewith the object codeformat 

bf dname, and rewrite it i n the same format. 

Show asummary of the opti ons to strip and exit. 

Treat theoriginal obj f i i e asafilewith the object codeformat 

b f d n a me . 

Replaceobj file with afilein the output format bf dname. 

Remove the named serti on from the fi le. Thisoption may be given 

morethan once. N otethat usi ng thisoption inappropri ately may 

make the object file unusable. 

Remove ali symbols. 

Remove debugging symbols only. 

Remove nonglobal symbols. 

Remove com pi ler-generated locai symbols. (Theseusually start with l 
or a peri od. 

Verbose output: listali object files modified. In the case of archives, 
strip -vlistsall membersof the archi ve. 
Show the version number for strip and exit. 
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subst 

su bs t— Su bsti tute def i n i ti ons i nto f i I e( s) 
SYNOPSIS 

subst [ -e editor ] -f substituti ons vieti m ... 

D ESC RIFIO N 

subst makes substitutions into files, in a way that is suitablefor customizing software to locai conditions. Eachv et i m file is 
altered accordi ngto the contentsof the subst i t ut i ons file. 

The substitutions fi le contai nsone li ne per substituti on. A line consists of two fidds separateci by oneor moretabs. The 
first field isthenameof thesubstitution, thesecond isthevalue. N either should contai n the character #, and useof text- 
editor metacharacterslike&and\ isalso unwise; thenamein particular isbest restri cted to alphanumeric. A li ne starti ngwith 
# isacommentand isignored. 

In thevictim files, each line on which a substituti on isto bemade (a target line) must bepreceded by a prototype li ne. The 
prototype line should be del imited in such a way that it will betaken asacomment by whatever program processesthefile 
later. The prototype li ne must contai n a prototype of the target line bracketed by = o< and >( )=; everythingelseon the 
prototype line isignored. subst extraets the prototype, changesall instancesof substituti on names bracketed by §< and >§to 
theirvalues, andthen repl aces the target line with the result. 

Substitutions are done usi ng the sed(l) editor, which must befound in either the /bm or /usr/bin directories. To specify a 
different executable, use the - e flag. 

EXAMPLE 

I f the substitutions file is 

FIRST 111 
SECOND 222 

and thevictim fileis 

x =2; 

/* =()<y =@<FIRST>9+@<SEC0ND>9;>()= */ 
y =88 +99; 
z =5; 

then subst -f substitutions victim ChangeS victim to 
x =2; 

/* =()<y =@<FIRST>@+@<SECOND>g;>()= */ 
y = 111 + 222; 
z =5; 

FILES 

vi et i mdi r /substtmp. new Newversion bei ng bui It 
vi et i mdi r / substtmp. old Old version during renami ng 

SEEALSO 

sed(l) 

DIAGNOSTICS 



Complainsand halts if it isunableto create its tempo rary files or if they al ready exist. 



SuperProbe 




HI STORY 

Written atUniversityof Toronto by H enry Spencer. 
Rich $alzadded the -e flagjuly, 1991. 

BUGS 

When creati ng a file to besubsted, it's easy to forget to insert a dummy target line after a prototype line; if you forget, subst 
ends up deleting which ever I i n e d i d i n f act follow the prototype line. 

Locai 



sum 

sum— C hecksum and counttheblocksin a file 
SYNOPSIS 

sum [-rs] [--sysv] [--help] [--version] [file...] 

D ESC RIFIO N 

Thismanual page documents the GN U version of sum. sum computesa 16-bit checksum for each named file, or the standard 
input if none are given or when a fi le named - isgiven. It printsthe checksum for each file along with thenumber of blocks 
in thefile (rounded up). By default, each correspondingfilenameisalso printed if at least two argumentsarespecified. W ith 
the - - sysv option, corresponding fi lenames are printed when thereisat least onefileargument. By default, the gnu sum 
computeschecksumsusing an algorithm that is compati ble with the BSD sum and pri nts fi le sizes in unitsof 1K blocks. 

OPTIONS 

-r Use the default (BSD -compati ble) algorithm. T hi s option isincluded for compati bility with the System V 

sum. Unlessthe -s option wasalso given, it hasno effect. 
-s, - - sysv Computechecksumsusingan algorithm that is compati ble with the one the System V sum usesby default 

and print file sizes in unitsof 512-byte blocks instead of 1K. 
- -heip Print ausagemessageand exit with a non-zero status, 

--version Print version information on standard output, then exit. 

GNU TextUtilities 



SuperProbe 

superPr-obe— Probe for and identify i ristali ed video hardware 
SYNOPSIS 

SuperProbe [-verbose] [-no16] [ - excl list] [-mask10] [ -order list] [ -noprobe I i s t ] [ - bios base] 
[-no bios] [-no dac] [-no meni] [-info] 

D ESC RIFIO N 

SuperProbe is a program that wi II attempt to determ ine the typeof video hardware installed in an ElSA/ISA/VLB-bus 
system by checking for known regi sters in vari ouscombi nati onsatvarious locati ons(M icroChannel and PCI machines may 
not befully supported; many work with the use of the -no_bios option.) Thisisan error-prone process, especially on UNIX 
(which usually hasa lot moreesoteric hardware installed than M S-DOS systemsdo), so SuperProbe may likely need help 
from the user. 
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superProbe runson SVR3, SVR4, Linux, 386BSD/FreeBSD/N etBSD, M inix-386, and M ach. Itshould betrivial to extend 
it to work on any other U N IX-like operati ng system, and even non-U N IX operati ng systems. Ali of the operati ng system 
(OS) dependenciesareisolated to asinglefileforeach OS. 

At thistime, superProbe can identify M DA, H ercules, CGA, M CGA, EGA, VGA, and an entirehordeof SVGA chipsets. 
(Seethe - info option under "Options") It can also identify several H iColor/True-color RAM D AC sin use on SVGA 
boards, and theamount of video memory installed (for many chipsets). It can identify 8514/ A and some deri vati ves, but not 
XGA, or PGC (although theauthor intendsto add thosecapabilities). N or can it identify other esoteric video hardware(like 
Targa, TIGA, or M icrofield boards). 



OPTIONS 

-verbose 
-no16 



-excl\l i st 



- maskl 0 



-order\ i st 



-noprobeM i st 



-bios\base 



-no_bios 

-no_dac 
- no_mem 
- info 



superPr-obe will be verbose and provi de lotsof information asit does itswork. 
superPr-obe will not attempt to use any portsthat requi re 16-bit I/O addressdecoding. The originai ISA 
busonly specified that I/O portsbedecoded to 10 bits. Therefore, some old cards (including many 8-bit 
cards) will misdecodereferencesto portsthat use the upper 6 bits, and may get into funny states because 
theythink that they are bei ngaddressed when they are not. It isrecommended that this option beused 
initially if any 8-bit cards are present in the system. 

superPr-obe will not attempt to access any I/O portson thespecified exclusion list. Some video cards use 
rather nonstandard I/O portsthat may conflict with other cards installed in your system. By specifying to 
superProbe, a I i st of ports al ready i n use, itwill know that therecannot be any video cards that usethose 
ports, and hence will not probe them (which could otherwise confuse your hardware). The exclusion list is 
specified asacomma-separated list of I/O ports or port ranges. A range is specified asi ow-hi gii, and is 
inclusive. The ports can be specified in decimai, in octal (numbers begin with 0), or hexadecimal (numbers 
begin with ex). 

Thisoption isused in combination with -exci. It telissuperProbe that when comparingan I/O port 
under test against the exclusion list, the port addressshould bemasked to 10 bits. Thisis important with 
older 8-bit cards that only do 10-bit decoding, and for some cheap 16-bit cards aswell. Thisoption is 
simply a less drastic form of the -noi 6 option. 

Thisoption specifies which chipsets superProbe should test, and in which order. The list parameter isa 
comma-separated list of chipset names. This list overridesthe built-in default testi ng order. To find the list 
of acceptablenames, use the - info option described later in this list. N otethat items displayed as 
"Standard video hardware" are not usable with the - order option. 

Thisoption specifies which chipsets superProbe should not test. The order of testing wi II either bethe 
default order, or that specified with the -order option. The list parameter isa comma-separated I i st of 
chipset names. To find the list of acceptable names, use the - info option. Note that items displayed as 
"Standard video hardware" are not usable with the -noprobe option. 

Thisoption specifies the base address for the graphics-hardware BIOS. By default, superProbe will 
attempt to locate the BIOS baseon itsown (thenormal address is 0x00000). If it failsto correctly locate 
the BIOS (an error messagewill beprinted if thisoccurs), the -bios option can beused to specify the 
base 

D isallow reading of the video BIOS and assume that an EGA or later (VGA, SVGA) board is present as 
the pri mary video hardware. 

Skip probi ng for the RAM DAC typewhen an (S)VGA isidentified. 
Skip probi ng for the amountof installed video memory. 

superProbe will print out a listi ng of ali the video hardware that it knowshow to identify. 



EXAMPLES 

To run superProbe in itsmost basic and automated form, simply enter thefollowing: 



SuperProbe 



tac 




NOTE 



You may want to redirect stdout to a file when you run superProbe (especi al ly if your OS does not su pport Virtual 
Terminalson theconsole). 

However, if you have any 8-bit cards installed, you should i n i ti al ly run superProbe as 

SuperProbe -verbose -no16 

(the - verbose option isincluded so you can seewhat superProbe isskipping). 
Finer granularity can beobtained with an exclusion list, for example, 

SuperProbe -verbose -excl 0x200,0x220-0x230,0x250 

will not test for any devicethat uses port 0x200, ports 0x220 through 0x230, inclusive, or port 0x250. If you have any 8-bit 
cards installed, you should add -maskio to the list of options. 

To restri et the search to Western D igital, Tseng, and Cirruschipset, run superProbe asfollows: 

SuperProbe -order WD, Tseng, Cirrus 

BUGS 

Probably a lot atthispoint. Please report any bugsor incorrect identificationsto theauthor. 

It is possi blethat superProbe can lock up your machine. Besureto narrow the search by using the - noi 6, -exci, and - 
maskio options provi ded to keep superProbe from conflicti ng with other installed hardware. 

SEEALSO 

Thevgadoc3.zip documentation package by Finn Thoegersen, avai lable in theM S-DOS archivesof many FTP repositories. 
Programmer'sGuidetotheEGA and VGA Cards, Second Edition, by Richard Ferrara. 

AUTHOR 

David E. Wexelblat (dwex@xfree86.org) with help from David Dawes (dawes@xfree86.org) and theXFree86 development 
team. 

Versi on 2.2 

tac 

tac— Concatenate and printfilesin reverse 
SYNOPSIS 

tac [-br] [-s separatori [--before] [--regex] [ - -separator=s e pa r at or ] 
[ - -help] [ - -version] [file...] 

DESCRIPTION 

Thismanual page documents the GN U version of tac. tac copieseach given file, or the standard input if none are given or 
when afilenameof - isencountered, to the standard output with the order of therecordsreversed. Therecordsareseparated 
by instancesof astring, or anewlineif none is given. By default, theseparator stri ng isattached to the end of the record that 
it follows in thefile. 
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OPTIONS 

Theseparator isattached to the beginningof the record that it precedesin the fi le. 
Theseparator isa regularexpression. 
U se s t r i n g as the record separator. 
Print a usage message and exit with a non-zero status. 
Print version information on standard output, then exit. 

GNU TextUtilities 



-b, - -bef ore 
-r, - -regex 

-s stri n g , - - separato r=s t r i n g 
- -help 
- - version 



tail 



tali— 0 utput the last part of fi les 
SYNOPSIS 

tail [-c [+]N[bkm]] [-n [+]N] [-fqv] [ - -bytes=[+]N[bkm] ] [ - -lines=[+]N] 
[--follow] [--quiet] [--silent] [--verbose] [--help] [--version] [file...] 

tail [{-,+}Nbcfklmqv] [file...] 

DESCRIPTION 

Thismanual page documents the GN U version of taii. taii prints the last part (10 lines by default) of each given file; it 
readsfrom standard input if no fi les are given orwhen afilenameof - isencountered. If morethan onefileisgiven, it prints 
a header consisti ngof the fi le'snameenclosed in ==> and <== before the output for each file. 

TheGN U taii can output any amountof data, unliketheU N IX version, which usesafixed size buffer. It hasno -r option 
(print in reverse). Reversi ng a fi le is really adifferentjobfrom printingtheend of a file; the BSD taii can only reverse fi les 
that are at most aslargeasits buffer, which istypically 32KB. A reliableand m ore versati I e way to reverse fi les is the GN U 
tao command. 

OPTIONS 

taii acceptstwo option formats: thenew one, in which numbersareargumentsto the option letters, and the old one, in 
which a + or - and optional number precede any option letters. 

If a number (n) startswith a+, taii beginsprintingwith the Nth item from the start of each file, instead of from the end. 

-c n, --bytes n Tail by n bytes. n isanon-zero integer, optionally followed byoneof thefollowing charactersto 
speci fy adifferentunit. 
b 512-byte blocks 
k 1-kilobyte blocks 
m 1-megabyte blocks 

-f, - -foiiow Loop forever, tryingto read more charactersat the end of the fi le, on theassumption that the fi le 

isgrowing. Ignored if readingfrom apipe If morethan onefileisgiven, taii pri nts a header 
whenever it gets output from adifferent file, to indicate which fi le that output isfrom. 

-ì, -n n, --lines n T ai I by n I i nes. - 1 is only recognized using the old option format. 

-q, - -quiet, --siient N ever print fi lename headers. 

-v, --verbose Always pri nt filmarne headers. 

- - help Print a usage message and exit with a non-zero status. 

- - version Print version information on standard output then exit. 
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talk 

talk— Talk to another user 
SYNOPSIS 

talk person [t t y n a me ] 

D ESC RIPTIO N 

talk is a visual communication program that copi es I i nes f rom your terminal to that of another user. 
T he followi ng opti ons are available: 

person If you wish to talk to someoneon your own machine, then person is just the person's login name. If you 

wish to talk to a user on another host, then person isof the form user ghost . 

tt yname If you wish to talk to a user who islogged in morethan once, thet t yname argument may beused to 

indicate the appropriate terminal name, wherett yname isof the form 

1 1 yx x 

W hen first called, talk sendsthe meSSageMessage from TalkDaemon@his_machine. . . : 

talk: connection requested by your_name@your_machine 
talk: respond with: talk your_name@your_machine 

to the user you wish to talk to. At thispoint, the recipient of themessageshould reply by typing 

talk your_name@your_machi ne 

It doesn't matter from which machine the recipient replies, as long ashis login name is the same. Once communication is 
established, thetwo parties may typesimultaneously, with their output appearing in separate Windows. Typing control -l 
" l wi II cause the screen to bereprinted, whileyour erase, km, and word km characterswill behavenormally. To exit, 
just type your interrupt character; talk then movesthecursorto thebottom of thescreen and resto res the terminal to its 
previ ous state. 

Permission to talk may bedenied or granted by useof themesg 1 command. At theoutset, talking isallowed. Certain 
commands, in particular nroft 1 and pr 1, disallow messagesin orderto prevent messy output. 

FILES 

/etc/hosts To find the reci pi ent's mach i ne 
/var/run/utmp To find the reci pient's tty 

SEEALSO 

mail(l), mesg(l), who(l), write(l) 

BUGS 

Theversion of talk 1 rdeased with BSD 4.3 uses a protocol that isincompatiblewith the protocol used in theversion 
released with BSD 4.2. 

HI STORY 

Thetaik command appeared in BSD 4.2. 

BSD 4.2, 22 Aprii 1991 
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tcal 

tcai— Runsthegcai program with the date oftomorrow's day 
SYNOPSIS 

tcal [ --help | --version ] ] [ - -shif t=[ + 1 - ]n u mb e r ] [Argument. . . ] 

D ESC RIPTIO N 

tcai is a program that runsgcai with a date set one day ahead (equivalentto the --snift=i option). Ali given arguments 
arepassed unmodified to thegcai program. If thegcai program shall becalled with adateother than tomorrow'sdate, this 
desired datecan beselected by usi ng the --shift=[+| - ]n u mbe r option, in which i + \ - ]n u mbe r isthenumber of daysthe 
desired date is distant from theactual date. The - - shif t option must be given beforeall other arguments, which arepassed 
to thegcai program. An exit status of 0 meansall processing issuccessfully done; any other valuemeansan errar has 
occurred. 

OPTIONS 

- -help 

- - version 

- - shift=[ + ] - ]n u mbe r 

ENVIRONMENT 

gcalprog T he gcalprog envi ronment vari able contai nsthefi lename of the executable gcai program, which 

isused by tcai to cali gcai. Takes precedenceoverthefilenamegcai, which isburned-in during 
thecompilation step of tcai. 

COPYRIGHT 

Copyright© 1995, 1996 by Thomas Esken. This software doesn't claim completeness, correctness, orusability. On principle, 
I will not be I iablefor any damages or losses (implicit or explicit), which resultfrom using or handlingmy software. If you 
use this software, you agreewithout any exception to this agreement, which bindsyou LEGALLY. 

tcai isfree software and distributed under the termsoftheGNU General Public License; published by the F ree Software 
Foundation; version 2 or (atyour option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposalsforcontractwork, and so forth are welcome! If 
you likethistool, l'd appreciatea postcard from you! 

Enjoy it =8") 
AUTHOR 

Thomas Esken (esken@uni-muenster.de) 

m H agenfdd 84 

D -48147 M uenster; Germany 

Phone: +49 251 232585 

SEEALSO 

gcal(l) 

16 July 1996 



Print a usage message listing ali available options, then exit successfully. 
Print the version number, then exit successfully. 

Definethedisplacement in [ + | -jnumber daysthe desired date is distant from theactual date. 
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telnet 

telnet— User interfaceto theTelnet protocol 
SYNOPSIS 

telnet [-d] [-a] [-n tracefile] [-e escapechar] [[-1 user] host [port]] 

D ESC RIFIO N 

Theteinet command isused to communicatewith another host using theTelnet protocol. If telnet isinvoked withoutthe 
host argument, itenters command mode, indicated by itsprompt teinet>. In thismode, itacceptsand executesthe 
commandslisted below. If it isinvoked with arguments, it performsan open command with thosearguments. 

OPTIONS 

-d Sets the initial valueof the debug toggleto True. 

-a Atterri pt automatic login. Currently, thissends the username via the user vari ableof the environ 

option if supported by theremote system. The nameused isthatof the current user asreturned 
by getiogin 2 if it agreeswith the current user ID; otherwise, it isthenameassociated with the 
user ID . 

-n tracefile 0 pens tracefile for recording trace information. See the set tracefile command in the 

"Commands" section. 

-ì user When connectingto the remote system, if the remote system understands the environ option, then 

userwill besentto the remote system as the value for the variable user. This option impliesthe -a 
option. Thisoption may also beused with theopen command. 

-e escape char Sets the initial telnet escape character to escape char. If escape char isomitted, then therewill 
be no escape character. 

host Indicatestheofficial name, an alias, or the Internet addressof a remote host. 

port Indicatesa port number (addressof an application). If a number is not specified, the default telnet 

port isused. 

Once a connection hasbeen opened, telnet will atterri ptto enable the telnetlinemode option. If thisfails, then telnet will 
revert to oneof two input modes— either character-at-a-timeor old li ne-by-l i ne, dependi ngon what the remote system 
supports. 

When linemode isenabled, character processing isdoneon the locai system, under the control of the remote system. When 
input editing or character echoing isto bedisabled, the remote system will relay that information. The remote system will 
also relay changes to any special characters that happen on the remote system, so that they can take effect on the locai system. 

In character-at-a-timemode, mosttexttyped isimmediately sentto the remote host for processing. 

In old li ne-by-l ine mode, ali text isechoed locai ly, and (normally) only completed lines are sentto the remote host. The locai 
echo character (initially "e) may beused to turn off and on the locai echo. (Thiswould mostly beused to enter passwords 
without the password being echoed.) 

If the linemode option isenabled, or if theiocaicnars toggleisTrue (the default for old line-by-line), theuser'squit, intr, 
and fiush characters are trapped locally, and sent as Telnet protocol sequencesto the remote side. If linemode hasever been 
enabled, then theuser'ssusp and eof are also sent as Telnet protocol sequences, and quit is sent as a telnet ABORTinstead 
of breakT nere are options (see toggie autofiush and toggie autosynch in thefollowing list) that cause this action to 
flush subsequent output terminal (until theremote host acknowledges the telnet sequence) and flush previous terminal 
input (in thecase of quit and intr). 
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close 

display argument. 
mode t y pe 



line 



ìsig -ìsig 



edit -edit 



softtabs 



COMMANDS 

Whileconnected to a remote host, telnet command modemay beentered bytyping the telnet escape character (initially 
"]). W hen in command mode, thenormal terminal editing conventi ons are available 

T he following telnet commands are available. 0 nly enough of each command to uniquely identify it need betyped. (This 
isalso truefor arguments to themode, set, toggie, unset, sic, environ, and display commands.) 

C losea telnet session and return to command mode. 
D isplaysall, or some, of the set and toggie values. 

t ype isoneof several options, dependi ng on the state of the telnet session. The remote host is 
asked for permission to go into the requested mode. If the remote host iscapable of entering that 
mode, the requested mode wi II beentered. Thet ype options are 
character D isable the telnet linemode option, or, if the remote side does not 

understand the linemode option, then enter character at atimemode. 
E nable the telnet linemode option, or, if the remote side does not 
understand the linemode option, then atterri pt to enter old-li ne-by-l i ne 
mode 

Atterri ptto enable(disable) the trapsig mode of the linemode option. This 
requiresthattheLiNEMODE option beenabled. 
Atterri ptto enable(disable) theEDiT modeof the linemode option. This 
requiresthattheLiNEMODE option beenabled. 

Atterri pt to enable(disable) the soft_tab mode of the linemode option. This 
requiresthat-softtabstheLiNEMODE option beenabled. 
ìitecho -ìitecho Attempt to enable (disable) the lit_echo modeof the linemode option. This 

requiresthattheLiNEMODE option beenabled. 
? Printsout help information for the mode command. 

open host Open a connection to thenamed host. If no port number isspecified, telnet wi 1 1 attempt to [ -1 

user ] [ -port ] contact a Tel net server at the default port. The host speci fi cati o n may beeither a hostname(see 

hosts(5)for more information) oran Internet addressspecified in the dot notati on (seemet(3) for 
more information). The -1 option may beused to specify theusernameto be passed to the remote 
system viatheENviRON option. W hen connectingto a nonstandard port, telnet omitsany 
automatic initiation of telnet options. W hen the port number ispreceded by a minussign, the 
initial option negotiation isdone. After establishing a connection, the fi le in the user's home 
directory isopened. Lines beginning with a# arecomment lines. Blank linesareignored. Lines that 
begin withoutwhitespace are the start of a machine entry. The first thingon thelineisthenameof 
the machine that is bei ng connected to. Therest of the line, and successive lines that begin with 
whitespace, areassumed to beteinet commands and areprocessed asif they had been typed in 
manuallyto the telnet command prompt. 
quit Closeany open telnet session and exit telnet. An end-of-file {in command mode) will also close a 

session and exit. 

send arguments Sends one or more special character sequencesto the remote host. The following are the arguments 
that may be speci fi ed (morethan oneargument may be specified at atime): 
abort Sends the telnet abort (Abort Processes) sequence. 

ao Sends the telnet ao (Abort Output) sequence, which should causethe 

remote system to flush ali output from the remote system to the user's 
terminal. 

ayt Sends the telnet ayt (AreYou There) sequence, to which the remote 

system may or may not chooseto respond. 
brk Sends the telnet brk (Break) sequence, which may havesignificanceto the 

remote system. 



telnet 




ec Sends the telnet ec (EraseCharacter) sequence, which should causethe 

remote system to erase the last character entered. 

ei Sends the telnet el (Erase Line) sequence, which should causethe remote 

system to erase thelinecurrentlybeing entered. 

eof Sends the telnet eof (E nd-of-F ile) sequence. 

eor Sends the telnet eor (End of Record) sequence. 

escape Sendsthecurrent telnet escape character (initially "). 

ga Sends the telnet GA(GoAhead) sequence, which likelyhas no significance 

to the remote system. 

getstatus If the remote side supports the telnet status command, getstatus will 

send thesubnegotiation to requestthat the server send itscurrent option 
status. 

ip Sends the telnet ip (Interrupt Process) sequence, which should causethe 

remote system to abort the currently running process. 

nop Sends the telnet nop (no operation) sequence. 

susp Sends the telnet susp (suspend process) sequence. 

syncn Sends the telnet sYNCHsequence.Thissequencecausestheremotesystem 

to discard ali previously typed (but notyet read) input. This sequence issent 
asTep urgent data(and maynotwork if the remote system isaBSD 4.2 
system— if it doesn't work, a lowercaser may beechoed on the terminal). 

? Printsout help information forthesend command. 

set argument vaiue, T he set command will set any one of a number of telnet variables to a specific value or to True. 
unset argument value Thespecial valueoft turns off the function associated with thevariable; thisisequivalentto using 

theunset command. The unset command will disableor set to False any of the specified 

functions. The valuesof variables may be i nterrogated with the display command. The variables 

that may beset or unset, but nottoggled, are listed here. In addi ti on, any of the variables for the 

toggie command may be expl icitly set or unset using the set and unset commands. 

echo This is the value (initially "e) which, when in line-by-line mode, toggles 

between doing locai echoing of entered characters (for normal processing), 
and suppressing echoing of entered characters (for entering, say, a password). 

eof If telnet is operati ng i n linemode or old line-by-line mode, entering this 

character as the first character on aline will cause this character to besentto 
the remote system. Theiniti al value of theeot character istaken to bethe 
terminal'seof character. 

erase If telnet ÌS in localchars mode (see toggle localchars, following), and if 

telnet is operati ng i n character at a ti me mode, then when this character is 
typed, a telnet ec sequence (see send ec, earlier in this man page) issent to 
the remote system. Theiniti al value for theerase character istaken to bethe 
terminal'serase character. 
escape T his is the telnet escape character (initially " [) which causes entry i nto 

telnet command mode (when connected to a remote system). 

flushoutput If telnet isin localchars mode (see toggle localchars) and the 

fiushoutput character istyped, a telnet ao sequence issent to the remote 
host. The initial value for the flush character istaken to betheterminal's 
flush character. 

interrupt If telnet ÌS i n localchars mode (see toggle localchars) and the interrupt 

character is typed, a telnet iup sequence is sent to the remote host. The 
initial value for the interrupt character istaken to bethe termi nal'sintr 
character. 
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kill 



lnext 



quit 



reprint 



start 



stop 



susp 



tracef ile 



worderase 



If telnet isin localchars mode (see toggle localchars), and if telnet ÌS 
operating in character at a ti me mode, then when thischaracter istyped, a 
telnet el sequence is sent to the remote system. T he ini ti al valuefor the 
km character istaken to be the terminali km character. 
If telnet is operati ng i n linemode or old line-by-line mode, then this 
character istaken to be the termi nal'sinext character. The initial valuefor 
the inext character istaken to be the termi nal'sinext character. 

If telnet ÌS in localchars mode (see toggle localchars) and thequit 

character istyped, a telnet brk sequence is sent to the remote host. The 
initial valuefor the quit character istaken to betheterminal'squit 
character. 

If telnet is operati ng i n linemode or old line-by-line mode, then this 
character istaken to be the termi nal's reprint character. The initial valuefor 
the reprint character istaken to betheterminal's reprint character. 
If theTELNETTOGGLE-FLow-coNTROL option hasbeen enabled, then this 
character istaken to betheterminal's start character. The initial valuefor 
the start character istaken to betheterminal's start character. 



sic state 



If the telnettoggle-flow-control option has been enabled, then this 
character istaken to betheterminal's stop character. The initial valuefor the 
kiii character istaken to betheterminal's stop character. 
If telnet isin localchars mode or linemode is enabled, and thesuspend 
character istyped, a telnet susp sequence is sent to the remote host. The 
initial valuefor thesuspend character istaken to be the terni inal'ssuspend 
character. 

Thisis the file to which the output, caused by netdata or option traci ng 
being True, will bewritten. If itissetto -, then tracing information will be 
written to standard output (the default). 

If telnet is operati ng i n linemode or old line-by-line mode, then this 
character istaken to betheterminal's worderase character. The initial value 
fortheworderase character istaken to betheterminal's worderase 
character. 

? D isplaysthe set unset commands. 

The sic command (Set Locai Characters) isused to set or change the state of the special characters 
when the telnetlinemode option has been enabled. Special characters are characters that get 
mapped to telnet command sequences(likeipor quit) or line-editing characters (like erase and 
kiii). By default, thelocal special characters are expo rted. Thevariablesare 



export 



import 



check 



Switch to the locai defaults for the special characters. T he locai default 
characters are thoseof thelocal terminal at the ti me telnet wasstarted. 
Switch to the remote defaults for the special characters. The remote default 
characters are those of the remote system at the ti me when the telnet 
connection wasestablished. 

V erify the current setti ngs for the current special characters. The remote side 
isrequested to send ali the current special character setti ngs, and if there are 
any discrepanti eswith thelocal side, thelocal si de will switch to the remote 
value. 

Prints out help information forthesic command. 
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environ arguments.. 



autof lush 



Theenviron command isused to manipulatethevari ables that may besentthrough the telnet 
environ option. The initial set of vari ables istaken from theusersenvironment, with onlythe 
display and printer variables being exported by default. The user vari ablei salso exported if the 
-a or -ì optionsareused. 
Valid arguments for the environ command are 

define «ari abi e vai ue D efi ne the variable v a r abi e to have a value of v a u e. A ny variables 
defined by thiscommand are automati cally exported. The value may 
beenclosed in single or doublé quotes so that tabs and spacesmay be 
included. 

undefine variable Removevari abi e from the list of environment vari ables. 

export variable M ark the variable v a r i abi e to beexported to the remote side, 

unexport variable M ark the variable v a r abi e to not beexported unlessexplicitly asked 

forby the remote si de. 

list List the current set of environment variables. Thosemarked with a* 

will besent automati cally; other variableswill onlybesentif explicitly 
requested. 

? Printsout help information for theenviron command. 

toggie arguments. . . Toggle (between True and False ) various flags that control how telnet respondsto events. These 
flagsmay be set explicitly to True or False using the set and unset commandslisted earlier. M ore 
than oneargument may be specifi ed. The state of these flags may be interrogateci with the display 
command. Valid arguments are 

If autof lush and ìocaichars are both True, then when the ao or 
quit characters are recognized (and transformed into telnet 
sequences; seeset for details), telnet refusesto display any data on 
the user's terminal until the remote system acknowledges(viaa 

TELNET TIMING MARK Option) that it h as prOCeSSed thOSe telnet 

sequences. The initial valuefor thistoggle isTrue if theterminal user 
had notdonean "stty nofisn"; otherwise, False. (Seestty(l) for 
more details.) 

If autosynch and ìocaichars are both True, then when either the 
intr or quit character istyped (see set for descriptionsof theintr 
and quit characters), the resulting telnet sequencesent isfollowed by 
the telnet synch sequence. This procedure should cause the remote 
system to begin throwing away ali previously typed input until both 
of the telnet sequences have been read and acted upon. T he initial 
value of this toggle is False. 

Enableor disable the telnet binary option on both input and 
output. 

Enableor disable the telnet binary option on input. 
Enableor disable the telnet binary option on output. 
If this is True, then carri age returns will besent as<CR><LF>. If this is 
False, then carriage returns will besent as<cR><NUL>. The initial 

valuefor thistoggle iSFalse. 

Toggle carriage return mode. When this mode isenabled, most 
carriage return characters received from the remote host will be 
mapped into a carriage return followed by a line feed. This mode does 
not affect those characters typed by the user, only those received from 
the remote host. T his mode is not very useful unless the remote host 
only sends carriage return, but never li ne feed. The initial valuefor 
thistoggle is False. 



autosynch 



binary 

inbinary 

outbinary 

crlf 



crmod 
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debug 



status 



? c o mma n d 



Toggles socket level debugging (useful onlyto the super user). The 

initial valueforthistoggle iSFalse. 
localchars If this ÌSTrue, then thetlush, interrupt, quit, erase, and kill 

characters (see set) are recognized locally, and transformed into 
(hopefully) appropriate telnet control sequences (respectively ao, ip, 
brk, ec, and ei ; see send). The initial valuefor thistoggle is True in 
old line-by-linemode and False in characteratatimemode. When 
the linemode option isenabled, thevalueof localchars isignored, 
and assumed to alwaysbeTr-ue. If linemode hasever been enabled, 
then quit issentasabort, and eof and suspend aresentaseof and 

susp; See send. 

netdata Toggles the display of ali network data (in hexadecimal format). The 

initial valuefor thistoggle is False, 
options Toggles thedisplay of some internai telnet protocol processing 

(having to do with telnet options). The initial valuefor this toggleis 

False. 

prettydump W hen the netdata toggle is enabled, if prettydump isenabled, the 

output from the netdata command will beformatted in a moreuser- 
readable format. Spacesareput between each character in the output, 
and thebeginning of any telnet escape sequenceis preceded by an * 
to aid in locati ngthem. 

? D isplaysthe legai toggle commands. 

Suspend telnet. This command only workswhen the user isusingthe csh(l). 

Execute a single command in asubshell on thelocal system. If command isomitted, then an 

interactive subshell isinvoked. 

Show the current status of telnet. T his includes the peer one is connected to, as well as the current 
mode. 

Get help. With no arguments, telnet printsa help summary. If a command isspecified, telnet 
will print the help information for just that command. 



ENVIRONMENT 

telnet usesat least the home, shell, display, and term environmentvariables. Other environment variablesmay be 
propagated to the other side vi a the telnet environ option. 

FILES 

-/ .teinetrc U ser customized telnet startup values 
HISTORY 

The telnet command appeared in BSD 4.2. 
NOTES 

On some remote systems, ecno hasto beturned off manually when in old line-by-linemode. 

In old li ne-by-l ine mode or linemode, the termi nal's eof character isonly recognized (and sent to the remote system) when it 
isthe first character on a line 



BSD 4.2, 27 July 1991 
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tfmtodit— Create font fi lesfor use with groff -Tdvi 



SYNOPSIS 



tfmtodit [ -sv ][-ggf file ][-kskewchar ] tfm file map file font 



DESCRIPTION 



tfmtodit createsafontfilefor use with groff -Tdvi. tfm_fiie isthe nameof thefont metric filefor thefont. map_fiie isa 
fi le givi ng the groff namesfor characters in thefont; thisfileshould consist of a sequence of linesof the forni: 



wheren isa decimai integer giving the positi on of thecharacter in thefont, and ci , 02, . . . are the groff namesof the 
character. If acharacter hasno groff namesbut existsin the tfm file, then it will beput in the groff font file asan unnamed 
character. font isthe nameof the groff font file. The groff font fileiswritten to font. 

The -s option should begiven if thefont is special (a font is special if troff should search it whenever a character is not 
found in the current font.) If thefont is special, it should belisted in thefonts command in theDEsc file; if it isnot special, 
there isno need to list it because troff can automatically mount it when it's first used. 

To do a good job of math typesetting, groff requiresfont metric informati on not present in the tfm file. Thereason for this 
isthat has separate math italicfontswhereas groff uses normal italicfontsfor math. The additi onal informati on required by 
groff isgiven by thetwo argumentsto thematn_fit macro in the M etafont programs for the Computer M odern fonts. In a 
textfont (a font for which matn_fitting is False), M etafont normally ignoresthesetwo arguments. M etafont can bemade 
to put this information in thegf fileby loading the followi ng definition after cmbase when creati ng cm.base: 

def ignore_math_fit(expr left_adjustment, right_adjustment) = 

special "ad] ustment" ; 

numspecial left_adjustment*16/designsize; 

numspecial right_adjustment*16/designsize; 

enddef ; 

Thegf filecreated usingthismodified cm.base should bespecified with the -g option. The -g option should not begiven 
forafontforwhich math_fitting istrue. 



n c1c2 



OPTIONS 



- gg f _f le 



-v 



-kn 



s 



P ri nt the versi on number. 

Thefont is special. The effect of this option isto add the special command to thefont file. 
Theskewchar of thisfont isat position n . n should bean integer; it may begiven in decimai, or with a 
leading 0 in octal, or with a leadingax in hexadeci mal. The effect of this option isto ignoreany kerns 
whosesecond component isthe speci fi ed character. 

gf _f i i e isa gf fileproduced by M etafont contai ni ng special and numspecial commands giving additi onal 
font metric information. 



FILES 



/usr/iib/groff /font/devdvi/DEsc D evice description file, 
/usr/iib/groff /f ont/devdvi/F Font description file for font F . 




Groff Versi on 1.09, 14 February 1994 
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tftp 

tftp— Trivi al file transfer program 



SYNOPSIS 

tftp [ho s t ] 

D ESC RIFIO N 

tftp is the user interface to the Internet tftp (Trivial Fi le Transfer Protocol), which allowsusersto transfer fi lesto and from 
a remote machine. The remote hostmay bespecified on thecommand line, in which case tftp useshost as the default host 
for future transfers. (Seetheconnect command in thefollowingsection.) 

COMMANDS 

Oncetftp isrunning, it issuestheprompt: 
tftp> 

and recognizesthefollowing commands: 



? c o mma n d ■ n a me ... 

ascii 

binary 

connect host-name port 



get filename, 

get remotename localname 

get f ilei f ile2 ... file 

mode transfer-mode 
put file 

put oc al f il e r e mot ef i I e 
put f i I el f i I e 2 ... 
f il e N remote-directory 



quit 
rexmt 

retransmission-ti meout 
status 
timeout 
total - 1 r a n s mi s s i on - 1 i meou 
trace 
verbose 



Print help information. 
Shorthand for "mode ascii" 
Shorthand for "mode binary" 

Set the host (andoptionallyport ) fortransfers. N otethattheTFTP protocol, unlikethe 
FTP protocol, doesnotmaintain connectionsbetween transfers; thus, theconnect 
command does not actually create a connection, but merely remembers what host is to be 
used fortransfers. You do not haveto use the connect command; the remote host can be 
speci fi ed as part of the get or put commands. 

Get a fileor set of filesfrom the specified sources. Sourcecan bein oneof two forms: a 
filenameon the remote host, if the host has al ready been specified; or a stri ng of theform 
n hosts:filenameto specify both a host and filenameat thesametime If the latter form is 
used, thelast hostname specified becomes the default for future transfers 
Set the mode for transfers; t r ansf er- mode may be ascii or binary. The default is ascii. 
Put a file or set of fi lesto the specified remote fi le or directory. The desti nati on can be 
in oneof two forms: a filenameon the remote host, if the host hasalready been specified; 
or a stri ng of theform hosts:fiiename to specify both a host and filenameat the same 
time. If the latterform isused, the hostname specified becomesthedefaultforfuture 
transfers. If the remote -directory form isused, the remote host isassumed to bea 
UNIX machine. 

Exit tftp . An end-of-filealso exits. 
Set theper-packet retransmission time-out, in seconds. 

Show current status. 

Set the total transmission time-out, in seconds. 



Togglepacket traci ng. 
Toggle verbose mode 



BUGS 



Becausethereisno user-login orvalidation within theTFTP protocol, the remote si te wi II probably havesomesort of file- 
access restri ctions in place. The exact methodsarespecific to each site and therefore difficult to document here. 



tifftopnm 



HI STORY 

Thetftp command appeared in BSD 4.3. 

BSD 4.3, 22 Aprii 1991 

tgatoppm 

tgatoppm— ConvertTrueV i si on Targa file into a portaPlepixmap 
SYNOPSIS 

tgatoppm [ -debug] [t gaf il e ] 

DESCRIPTION 

ReadsaTrueVisionT arga f i le as i n put. P roduces a portabl e pi xmap as output. 
OPTIONS 

-debug C auses the header informati on to Pedumped to stderr 
Ali flags can PeaPPreviated to their shortest unique prefix. 

BUGS 

Should really Pe in pnm, not ppm. 
SEEALSO 

ppmtotga(l), ppm(5) 

AUTHOR 

P arti al ly Pased on tga2rast, version 1.0, by lan J. M acPhedran 
Copyright© 1989 Pyjef Poskanzer. 

26 August 1989 

tifftopnm 

tifftopnm— C onvert a T I FF file into a portaPle anymap 
SYNOPSIS 

tifftopnm [ -headerdump] tifffile 

DESCRIPTION 

tifftopnm readsaTIFF fi le as input and produces a portaPle anymap as output. The type of the output file dependson the 
input fi le; if it'sblack and white, a pbm file is written;, if it'sgrayscale, a pgm file; otherwise, a ppm fi le. The program tellsyou 
which type it iswriting. 

OPTIONS 

-header-dump Dump TIFF file informati on to stderr. This informati on may Peuseful in debugging TIFF file 
conversi on proPlems. 

Ali flags can PeaPPreviated to their shortest unique prefix. 
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SEEALSO 

pnmtotif f(l), pnm(5) 

BUGS 

This program isnot self-contained. To useityou must fetch theTIFF Software package li sted in the other . systems fi le and 
configure pbmpius to useiibtiff . Seethepbmpius Makefiiefordetailson this confi guration. 

AUTHOR 

Derived byjef Poskanzerfrom tif2ras.c, which is copyright 6 1990 by Sun M icrosystems, Inc. Author Patrick J. Naughton 

(naughtonOwind . sun . corri). 

13 January 1991 
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tin, rtin, cdtin, tind— A N etnews reader 
SYNOPSIS 

tin/rtin/cdtin/tind [ opti o n s ] [newsgroups ] 

D ESC RIFIO N 

tin isafull-screen easy-to-use N etnews reader. It can read news locally (/usr/spooi/news) or remotely (rtin or tin -r 
option) viaan N NTP (Network N ewsTransport Protocol) server, cdtin can read news locally and news archi ved on CD- 
ROM . Itwi II automati cally util izenov (news overview)-style index fi lesif available locally or via the nntp xovercommand. 

tin hasfive separate levelsof operation: group selection level, spooidir selection level, group level, thread level and article 
level. Use the n (help) command to view a list of the commands available at a parti cular level. 

On startup, tin will show a list of the newsgroups found in $HOME/.newsrc. An arrow -> or highlighted bar will pointto the 
first newsgroup. M ove to a group by using the terminal arrow keys (termi nal-dependent) or j and k. UsePgU p/PgD n 
(termi nal-dependent) or Ctrl-U and Ctrl-D to pageup/down. Enter a newsgroup by pressing Return. 

TheTab key advancesto thenext newsgroup with unread articles and enters it. 
0PTI0NS 

-c C reate/update index fi lesfor every group in $HOME/.newsrc or fi le specified by -f option and mark ali 

articles as read. 

-t file Use the specified fileof subscribed to newsgroups in place of $HOME/.newsrc. 

-h H el p I isti ng ali command-lineoptions 

-h B ri ef i Production to tin that isalso shown the first ti me it isstarted. 

- 1 dir D irectory in which to store newsgroup index files. Default ìs$home/. tin/ .index. 

-m dir M ailbox directory to use. Default is$HOME/Maii. 

-m user Mail unread articlesto specified user for later reading. Formoreinformation read the "Automatic M ailing 

and Saving N ew N ews" section later in thismanual page, 
-n Only load groupsfrom the active fi le that are also subscribed to in theusers .newsrc. Thisallowsa 

noticeablespeedup when connectingviaaslow line, 
-p program Print program with options. 
-q Quick start without checking for new newsgroups. 

-p Purge group i ndex fi lesof articles that no longer exist. Careshould betaken when using this command as 

it startseach and every article in each group that isaccessed. On a low-speed connection, this can havean 
undesirable effect and it also knocksthehell out of yourfilesystem. 
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-r Read news rem otely fra m the default N NTP server specified in the environment variable nntpserver or 

COntained in thefile /etc/nntpserver. 

-r Read newssaved by -soption (notyet implemented). 

-s dir Savearticlesto directory. Default is$HOME/News. 

-s Saveunread articlesfor later reading by -r opti on. For moreinformation, see "Automatic M ai li ng and 

Saving N ew N ews." 

-u Create/updateindexfilesfor every group in $HOME/.newsrc or file specified by -f option. T his option is 

disabled if tin retri eves its index files via an N NTP server, 
-u Start tin in the background to update index fi leswhi le reading news in the foreground. T his option is 

disabled if tin retri eves its index files via an N NTP server, 
-v Verbose mode for -c, -m, -s, -u, and -zoptions. 

-w Quick modeto post an article and then exit. 

-z Only start tin if thereisany new/unread news. If thereis news, tin will position cursorat first group with 

unread news Useful for putti ng in loginfile. 
-z Check if thereisany new/unread news and exit with appropriate status. If -v option i s specified, the 

number of unread articlesin each group isprinted. An exit codee indicatesno news, 1 that an errar 

occurred, and 2 that new/unread news exists. U seful for writing scripts. 

tin can al so dynamically changeitsoptions by theM menu command. Any changes arewritten to $HOME/.tin/tinrc. 
Theindexdaemon version, tind, only supports the -t, -n, -i.and -voptions. 

INDEX FILES 

In order to keep track of threads, tin maintainsan index for each newsgroup. There are a number of methodsin which 
index files can becreated and updated. 

Thesimplest method is that each user creates/updates his or her own index fi lesthat are stored in $home/. tin/ .index. T his 
has the advantage that any user can compile and instali tin, but the disadvantageis that each user isgoingto be creati ng 
duplicate files and using preci ous disk space A good way to keep index files updated is by doing a tin -u that will update 
index files in the background whileyou are reading news in the foreground. You can also update index files vi a the system 

batcher cron with the -u Option: 30 6 ***/usr/local/bin/tin -u. 

A slightly better method isto set tin setuid news and haveall index fi lescreated and updated in the news spool directory 
(that is, /usr/ spooi/news/. index). This has the advantage that there will only beone copy of the index files on each 
machine on your network, but the disadvantageis that you will havetin running setuid news. 

A better method isto instali the tind indexfileupdatingdaemon and haveit create and update index files for ali groupsin 
your acti ve file at regular intervalsin the news spool directory (/usr/ spooi/ news/, index). This has the advantage that there 
will only beonecopy of the index files on each machine on your network, and tin must not be setuid news, but the 
disadvantageis that you will haveto havenewspermissionsto instali tind and root permissionsto instali an entry in the 
cron batcher system to havetind regularly update index files. 

Thebest method isto instali the tind indexfileupdatingdaemon on your N NTP server and haveit create and update index 
files for ali groupsin your acti ve file at regular intervalsin the news spool directory (/usr-/ spool/ news/, index). This has the 
advantage that there wi II only be one copy of the i ndex fi les on the N N T P server for the whole of your network, but the 
disadvantageis that you will haveto instali my N NTP server patchesto allow tin to retri ève index fi le from your N NTP 
server and you must instali an entry in the cron batcher system to havetind regularly update index fi les. (T his is the method 
we use on our network of 40 to 50 machines and we have not had any problems.) 

Entering a group the first timetendsto beslow because the index fi le must be bui It from scratch unless the tind update 
daemon is bei ng used. To al leviate the slowness, start tin to create ali index fi les for thegroupsyou subscribeto with 
tin -u -v and go for a coffee. Subsequent readingsof a group will cause incrementai updatingof the index file. 
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If reading news remotely and locally updating index fi les operati on will besomewhatslower because the artici es must be 
retrieved from theN NTP server. 

NEWS ADMINISTRATIO N 

M aintaining Netnewson largenetworksof machinescan bea pretty time-consumingjob, asl discovered when I wasgiven 
the job of maintaining our news system and newsusers. 

tin isa N ewsUser Agent and so most of theuserswerealwaysasking questionsor doing thingsthat could befrowned upon 
by their departments. To relieve news administrators (and especially me) of this, featureshavebeen added to makelifeeasier 
forthem. 

When auserstartstm, it is possi bleto inform them of any important changesor information concerni ng the news system by 
displayingamessageof theday (motd) file. The mota fileshould becreated in your news li b directory (/usr/iib /news /motd) 
and should have fi le pernii ssions set to 0644. T he motd fi le will only bedisplayed if itscontentsis newerthan thelasttime 
the user started tin. If reading news via N NTP, my xmotd patch will haveto havebeen appi i ed to your N NTP server. 

A user starti ng tin for the first ti me can be automati cai ly subscribed to a list of newsgroupsthat aredeemed appropriate by 
the news administrator. At our site the subscri ptions file has 125 groups (our acti ve fi le contai ns more than 400 groups with 
many only being marginai ly interesting to most people). The subscri ptions fi le should becreated in your news lib directory 
(/usr/iib/news/subscniptions) and should havefile permissionsset to 0644. If reading news via N NTP, my list 
subscriptions patch will haveto havebeen applied to your N NTP server. 

If my N NTP xuser patch has been applied to your N NTP server, you will beableto log theusernameand machineto your 
NNTP logfilefor usage stati stics. 

SCREEN FORMAT 

tin has five separate levelsof operation: group selection level, spooidir selection level, group level, thread level, and article 
level. 

At the group selection level, the title displays the number of subscribed groups. The newsgroups are di splayed on theleft of 
thescreen with thenumber of unread articles di splayed on thesamelinein themiddleof thescreen, likethis: 

<Selection NumxNewsgroupxNum of unread articles> 
i.e. , 

1 alt.sources 10 

2 comp.sources.misc 3 

3 news. software. readers 12 

At the group level, the title contai ns the nameof the group, thenumber of conversation threads, and total number of articles, 
for example, alt.sources (7 23). If the group has been set up notto thread articles (for example, alt.sources isin 
$(home) / .tin/unthread), the title wi II be alt . sources (u 23). There aretwo possi ble display formats: 

<Selection Num><Unread><Responses><Sub] ect><Author> 
e.g. , 

1 + 3 Bnews sources? iain@anl433 . uucp 

2 1 This question has ether@net 

or 

<Selection Num><Unread><Responses><Sub] ect (longer)> 
e.g. , 

1 + 3 Bnews sources? 

2 1 This question has a longer subj ect line 

At the article level, the page header has thefollowing format: 



<Date posted><Newsgroup> 
<Thread 1 of n> 

<Article NumxSubjectxNum of responses in thread> 
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<Author><Organization> 
<Article body> 
i.e. , 

24 Jul 15:20:03 GMT 
Artide 452 
iain@anl433.uucp 

COMMON MOVINGKEYS 

T he following tableshows the common keys/commandsfor moving at ali five levels within tin: 
Begi nning of list/article Home 1 ("Rorg atarticlelevel) 



End of list/article End $(alsoG atarticlelevel) 

Pageup PgUp "u or "b or b 

Page down PgDn "Dor "For<sPACE> 

Lineup up arrow k (not at article level) 

Linedown Down arrow j (not at article level) 

COMMON EDITING COMMANDS 

An emacs-style editing package allows the easy editing of input stri ngs. A history list ali ows the easy reuseof previ ously 
entered strings. Thefollowingcommandsareavailablewhen editing a string: 

-a, -e M oveto beginningor end of line, respectively. 

-F, -B Nondestructivemoveforward or back one location, respectively. 

-D Delete the character currently under the cu rsor, orsend eof if no charactersarein the buffer. 

-H, <del> D elete character left of the cursor. 

"K D elete from cursor to end of line. 

-p, -N M ovethrough history, previousand next, respectively. 

*l, -r Redraw thecurrent line. 

<cr> Places line on history list if nonblank, appendsnewline, and returnsto the Caller. 

<esc> Aborts the present editing operati on. 

NEW SGROUPSELECTION COMMANDS 

4 Select group 4. 

-K D elete current group from $HOME/.newsrc file. 

-L Redraw page 

"R Reset $HOME/.newsrc file. 

<cr> Read current group. 

<tab> View next group with unread news. W ili wrap around to the begi nning of the group selection list looking 

for unread groups. 

b M ai I a bug report or commentto theauthor. Thisisthebest wayto get bugsfixed and featuresadded/ 

changed. 

c M ark current group asall read with confi rmation and go to next group in group selection list. 

c M ark current group as ali read and go to next unread group in group selection list. 

d Toggle display to show just the group name or the group nameand the group's descri ption. 

g Chooseanew group by name. The position of the group within the group list wi II also beasked for. When 

1 isentered, thenew group will bethefirst group in thedisplayed list; when 8 isentered, thegroup will be 
theeighth group in the list; and so on. When $ isentered, thegroup will be the last group displayed. 



alt.sources Thread 1 of 2 

Bnews sources? 3 responses 

Organization name 
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h H elp screen of newsgroup selection commands. 

h Togglethedisplay of help mini-menu atthebottom of thescreen. 

i Toggle inverse video. 

1 List and allow selection of the available spool directories. Thisfeaturerequi resa special library to belinked 

with tin to create cdtin, which can then read newsfrom an activenewsfeed and also from multiple CD- 
ROM s. 

m M ovethecurrent group within thegroup selection list. W hen 1 isentered, thegroup will become the first 

displayed group in the list; when 8 isentered, theeighth group in the list; and so on. W hen $ isentered, 
thegroup will bethe last group displayed. 

m User-configurableO ptionsmenu (for moreinformation, see the "Global OptionsM enu" section later in 

thismanual page). 

q Quittin. 

Q Quittin. 

r Toggle display of ali subscribed-to groups and just the subscribed-to groupscontainingunread articles. 

Command hasno effect if groups were read from thecommand li ne when tin wasstarted. 

s Subscribeto current group. 

s Subscribeto groups matching user-specified pattern, 

u U nsubscri be to current group. 

u U nsubscri beto groups matching user-specified pattern, 

v Printtin version information. 

w Post an articleto current group. 

w List articles posteci by user. The date posted, the newsgroup, and the subject are I i sted . 

y The first ti me this command i scali ed, it will yank in ali groups from $i_iB-DiR/active that arenot in 

$HOME/ . news re. 

After any groups havebeen subscribed/unsubscribed to, thiscommand, if pressed again, will reread$HOME/ 

.newsrc and display only thesubscribed groups. 
y Reread theactivefileto see if any new news hasarrived since starti ng tin. 

z Markall articles in the current group asunread. 

z U ndeletepreviously deleted group by "k command from $home/. newsrc. 

/ Group forward search. 

? Group backward search. 

SPOOL DIRECTORY SELECTION COMMANDS 

4 Select spool directory 4. 

-L Redraw page 

<cr> Read newsfrom selected spool directory. 

b M ai I a bug report or commentto theauthor. This is the bestwayto get bugsfixed and features 

added/changed. 

h H elp screen of spool directory selection commands. 

h Togglethedisplay of help mini-menu atthebottom of thescreen. 

i Toggle inverse video. 

q Return to previ ous level. 

Q Quittin. 

v Printtin version information. 
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GROUP INDEX COMMANDS 



4 Sei ect arti de 4. 

-K Kill current article (for more informati on, see the "Automatic Kill and Selection" section later in this 

manual page). 

-L Redraw page 

<cr> Read current article. 

<tab> View next unread article or group. 

a Authorforward search. 

a Author backward search. 

c M ark ali articlesasread with confirmation. 

c M ark ali articles as read and go to next group with unread news, 

d Toggle display to show just the su bj ect orthesubject and author. 

g Chooseanew group by name. 

h H elp screen of group index commands. 

h Togglethedisplayof help mini-menu atthebottom of thescreen. 

i Toggle inverse video. 

k M ark article/thread as read and advanceto next unread arti ci e/th read. 

1 List the author of each responsein current thread and enterthread selection level. 

m M ail current arti clcVth read/auto-sel ected (hot) articles/articles matching pattern/tagged articles to someone. 

m User-configurableO ptionsmenu (for more informati on see "Global 0 ptionsM enu" section). 

n Go to next group. 

n Go to next unread article. 

o Output current arti ci e/th read/ autosel ected (hot) articles/articles matching pattern/tagged articles to 
pri nter. 

p Go to previ ous group. 

p G o to previ ous un read arti ci e 

q Return to previous level. 

Q Quittin. 

s Save current arti c I e/th read/ autosel ected (hot) articles/articles matching pattern/tagged articles to file/files/ 

mailbox. To saveto a mailbox, enter = or =maiibox when asked for filenameto saveto. To save in 
newsgroup name>/<f iiename> format, enter +f iiename. E nvi ronment variables areallowed within a 
fi lename (for example, $souRCEs/dir/f iiename). 

t Tag current article/thread for mailing (m)/piping (Imprinting (o)/saving(s)/crossposting(x). 

u Toggle display to show ali articles asunthreaded or threaded. 

u U ntag ali articles thatweretagged. 

v Printtin version information. 

w Post an article to current group. 

w List articles posted by user. The date posted, the newsgroup, and the subject arelisted. 

x C rosspost al ready posted current arti ci e/th read/autosel ected (hot) articles/articles matching pattern/tagged 

articles to another newsgroup) s). Useful for repostingfrom global to locai newsgroups. 
x M ark ali unread articles that havenot been selected asread, redo screen to refi ect changes, and put index at 

the first thread to begin reading. Pressing x again will toggle back to theway it wasbefore. See ■ command 

f o r ci eari n g th e toggl e ef f ect. 
z M ark current article as unread. 

z Mark current thread as unread. 



522 
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/ Search forward for specified subject. 

? Search backward for specified subject. 

Show last message. 

I Pipecurrent article/thread/autoselected (hot) articles/articles matching pattern/tagged articles into 

command. 

Select current thread for later processing. 

Toggleselection of current thread. If at least oneunread art in thread (but not ali unread arts) isselected, 

then ali unread arts becomeselected. 
@ Reverse ali selectionson ali articles. 

U ndo ali selectionson ali articles. It clears thetoggle effect of x command. Thus, after first doing an x, you 

can then do " to reset articles. Thus, you can iteratively whittle down uninteresting threads. 
+ Perform autoselection on current group. 

; Foreach thread in current group, if it at least oneunread art isselected, ali unread arts becomeselected. 

Thisisuseful for autoselection on authorwhen thereaderwantsto see the enti re thread. 
Promptsfor a pattern with which to match on. AH threads whosesubjects match the pattern will be 
selected. A pattern of * will match ali subjects. Entering just <cr> will cause the previ ous pattern to be 
used. 

THREAD LISTING COMMANDS 

4 Select article 4 within thread. 

-L Redraw page 

<cr> Read current articlewithin thread. 

<tab> View next unread articlewithin thread. 

b M ai I a bug report or commentto theauthor. This is the bestwayof getti ng bugsfixed and featuresadded/ 

changed. 

c M ark thread as read after confirmation and return to previous level. 

d Toggle display to show just the subject or the subject and author. 

h Helpscreen of thread listing commands. 

h Togglethedisplayof help mini-menu atthebottom of thescreen. 

i Toggle inverse video. 

k M ark thread as read and return to previous level. 

q Return to previous level. 

Q Quittin. 

r Toggle display to show ali articles or only unread articles. 

b M ai I a bug report or commentto theauthor. This is the bestwayof getti ng bugsfixed and featuresadded/ 
changed. 

t Tag current articlefor mailing (m)/piping (Imprinting (o)/saving(s)/crossposting(x). 

t Return to group index level. 

v Printtin version information. 

z M ark current articlein thread asunread. 

z M ark ali articles in thread asunread. 

ARTICLE VIEWER COMMANDS 

b Read the base article in thisthread. 

4 Read response4 in thisthread. 

"H Show ali of the arti ci e's mail header. 
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-K Kill current article (for moreinformation, see the "Automatic Kill and Selection" section) 

~l Redraw page 

<cr> Go to next base article. 

<tab> Go to nextunread article. 

a Authorforward search. 

a Author backward search. 

c M ark ali articles as read with confi rmation and return to group selection level. 

c M ark current group as ali read and go to next unread group in group selection list, 

d Togglerot-13 decodi ng for this article. 

d Delete current article. It must havebeen posted by the same user. The cancel messagecan beseen inthe 
newsgroup control. 

f Post a follow-up to the current article with a copy of the article i ncluded. 

f Post a follow-up to the current article. 

h H elp screen of article page commands. 

h Togglethedisplay of help mini-menu atthebottom of thescreen. 

i Toggle inverse video. 

k M ark article as read and advanceto next unread article 

k M ark thread as read and advance to next unread thread. 

m M ail current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles to someone. 

m User-configurableO ptionsmenu (for moreinformation, see the "Global OptionsM enu" section later in 

thismanual page), 

n Go to the next article. 

n Go to the next unread article. 

o Output current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles to 
pri nter. 

o Output article/thread/tagged articles to printer. 

p Goto the previous article. 

p Go to the previous unread article. 

q Return to previous level. 

Q Quittin. 

r Reply through mail to the author of the current arti de with a copy of the arti dei ncluded. 

r Replythrough mai I to the author of the current article. 

s Save current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles to file/files/ 
mailbox. To saveto a mailbox enter = or =maiibox when asked for filenameto saveto. To save in 
newsgroup name>/<f iiename> format, enter +fiiename. Environment variables are allowed within a 

filename(SUCh aS$SOURCES/dir/f ilename). 

t Return to group selection level. 

t Tag current arti de for mailing (m)/piping ( | )/printing (o)/saving (s)/crossposting (x). 

v Printtin version information. 

w Post an article to current group. 

w List articles posted by user. The date posted, the newsgroup and the subject are listed. 

x Crosspost al ready posted current article/thread/autoselected (hot) articles/articles matching pattern/tagged 

articles to another newsgroup) s). Useful for repostingfrom global to locai newsgroups. 

z M ark article as unread. 

/ Article forward search. 

? Article backward search 
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I Pipe current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles i nto 

command. 

< Go to the first article in the current thread. 

> Go to thelast article in the current thread. 

Select current thread for later processing. 

Toggle selection of current article. 
@ Reverse articleselections. 

U ndo ali sei ections on current thread. 

GLOBAL OPTIONS MENU 

Thismenu isaccessed by pressing m at ali levels. It allowstheuser to customizethebehavior of tin.Theoptionsaresaved to 
thefile$H0ME/.tin/tinrc. U se <space> to togglethe required option and <cr> to set. 



Auto save 

Editor offset 

M ark saved read 
Confimi Command 

D raw arrow 
Print header 

Go to lst unread 

Serali full page 
Catch up on quit 

Thread articles 



Show only unread 
Show descri ption 

Show Author 



Processtype 



Automatically save arti cles/threadsby "Archi ve-name:" li ne in article header and post processthem 
if processtype isnot setto None. 

Set on if the editor used for posting, follow-upsand bug reports hasthecapability of starti ng and 

positioning the cursor at a specified linewithin afile. 

Allows saved articles/threads to be automatically marked as read. 

Allows certain commands(such asc catcnup) thatrequireuser confirmation to beexecuted 

immediately if set off. 

Allows groups/articlesto beselected by an arrow -> if set on or by a highlighted bar if set off. 
This allows the complete mail header or only the "Subject:" and "From:" fieldsto be output when 
printing articles. 

Thisallowsthecursorto beplaced at the fi rst/last unread article upon entering a newsgroup with 
unread news. 

If set on, scrolling of groups/articleswill bea full pageatatime; otherwise, half a pageat atime. 
If set on, the user isasked when quitti ng if ali groups read during the current session should be 
marked read. 

If set on, articles will bethreaded in ali groups (default); otherwise, articles will beshown 
unthreaded. Threadingor unthreading is possi bleon a per-group basis by setti ng the group 

attribute variable thread_arts tO ON/OFF inthefile$HOME/,ti n/attri butes. 

If set on, show only new/unread articles; otherwise, show ali articles. 

If set on, show a short descri pti ve text for each displayed newsgroup. The text used istaken from 

the $LIBDIR/newsgroups file. 

If set None, only the "Subject:" li ne will be displayed. If set Addr, "Subject:" line and theaddress 
partof the "From:" line are displayed. If set Name, "Subject:" I ine and the author's full namepartof 
the'Trom:" lineare displayed. If setBotn, "Subject:" lineand ali of the'Trom:" linearedisplayed. 
This specifies the default typeof post processing to perform on saved articles. T he followi ng types 
of processing are allowed: 

■ N one 

■ U npacking of multipari: shell archives 

■ U npacking of multipari: uuencoded files 

■ U npacking of multipari: uuencoded files, which producea * 
listed 

■ U npacking of multipari: uuencoded files, which producea < 
extracted 

■ U npacking of multipari: uuencoded files, which producea *. zip archivewhosecontentsare 
listed 



.zoo archivewhosecontentsare 
.zoo archivewhosecontentsare 
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Sort arti ci es by 



Save directory 
M ail directory 



Printer 



■ U npacking of multi part uuencoded files, which produce a *. zip archivewhosecontentsare 
extracted 

■ U npacking of multi part uuencoded files, which produce an *.ina archivewhosecontentsare 
listed (AmigaD OS versi on only) 

■ U npacking of multipari: uuencoded files, which produce an *.ina archivewhosecontents is 
extracted (AmigaD OS versi on only) 

This speci fi es how articlesshould besorted. Thefollowing sort types areallowed: 

■ D on't sort articles (default). 

■ Sort articles by "Subject:" field (ascending and descending). 

■ Sort articles by "From:" field (ascending and descending). 

■ Sort articles by "D ate" field (ascending and descending). 

Thedirectory where arti ci es/thread sarete besaved. Default is$HOME/News. 
Thedirectory where arti cles/threads areto besaved in mailbox format. Thisfeatureismainlyfor 
usewith the eim mail program. It allows the user to save articles, threads, orgroupssimply by 
givi ng = asthefilenameto saveto. 

The printer program with optionsthat iste beused to print articles. Default isiprfor BSD 
macnines and ip for SysV machines. 



tinrc CO N FIG U RABLE VARI ABLES 

Thefollowing vari ables are user-configurableby editing $HowiE/.tin/tinrc directly. It ishoped to eventually providea menu 
to allow the setti ngof the most common vari ables. 

If set on, articles/threads will besaved in batch modewhen save-sormail -m isspecified on 
thecommand line Default ìsoff. 

If set on, a mini-menu of the most useful commandswill bedisplayed atthebottom of the 
screen for each level. Default ìson. 

Theprompt Reading. . . will bedisplayed when reading an articlefrom an N NTP server to 
provide feedback to the user. D efault ìson. 

Specifies whether a screen redraw should always bedone after certain external commands. 
Default ìsoff. 

M aximum length of thenamesof newsgroupsto bedisplayed so that more of the 
newsgroup descri ption can bedisplayed. D efault is 132. 

Thepath that specifies the signature fi lete use when posti ng, followingup to, or replyingto 
an arti de. If thepath is a directory, then the signature will berandomly generated from files 
that are in the specified directory. Default is$HOME/.sig. 

T he format stri ng used to create the editor start command with parameters. D efault ìs%e 

+%N %F (for example, /bin/vi +7 .article). 

Thecharacter used to show that an article/thread isautoselected (hot). Default is*. 
Thecharacter used in quoti ng included text to article follow-ups and mail replies. The 1 ' 
character represents a blank character and is replaced with 1 1 when read. D efault is 1 : 1 . 
Thenewsactivefileisreread at regular intervals to show if any new news hasarrived. 
D efault ÌS30O seconda 

Thecharacter used to show that an arti de will return. Default is -. 
Allows articles to besaved to an mmdf-stylemailboxinstead of mbox format. D efault ìsoff 
unless reading newson SCO U N IX, which uses mmdf by default. 
Thelast li ne of the previ ous page will bedisplayed as the first lineof next page. Default is 
off. 



batchsave 
beginner_level 
display_reading_prompt 
f orce_screen_redraw 
groupname_max_length 
default_sigf ile 

editor_f ormat 

hot_art_mark 
quote_chars 

reread_active_file_secs 

return_art_mark 
save_to_mmdf_mailbox 

show_last_line_prev_page 
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slow_speed_terminal 

tab_after_X_selection 

tab_goto_next_unread 

unread_art_mark 
use_builtin _inews 
usekeypad 



Stripstheblanksfrom the end of each line, thereby speedingup the display when reading 
on a slow terminal or via modem. Default ìsoff. 

If enabled, will automati rally go to the first un read arti eie after having selected ali hot 
articles and threadswith thex command at group index leve!. D efault ìsoff. 
If enabled, pressing T ab at the article Viewer leve! will go to thenext unread article 
immediately instead of first paging through thecurrent one. Default is on. 
Thecharacter used to show that an article hasnot been read. Default is+. 
Allowsthebuilt-in N NTP inews to be enabled/di sabled. Default ìson (enabled). 
Allows the scroi I keyson the keypad to beenabled/disabled on supported terminals. Default 
ìsoff. 



GROUPATTRIBUTES 

tin allows certain attri butes to beset on aper-group basi s. These group attributes are read from thefile$HOME/.tin/ 
attributes. A later version will providea menu interface to set ali the attri butes. At present, you will haveto edit the fi le 
with your editor :-(. Thefollowing group attri butes are available: 

newsgroup=alt . sources 

maildir=/usr/iain/Mail/sources 

savedir=/usr/ìain/ News /alt . sources 

sigf ile=/usr/iain/ .funny sig 

organization=Wacky Bits Inc. 

followup to=alt. sources. d 

printer=/usr/local/bin/a2ps -nn ] /bin/lpr 

auto save=ON 

batch save=OFF 

delete tmp files=ON 

show only unread=OFF 

thread arts=0N 

show author=1 

sort art type=5 

post proc type=1 

N ote that the newsgroup=<groupname> linehasto be specified beforethe attributes are specifiedfor that group. 

Ali attri butes are setto a reasonable default so you only haveto specify the attri bute that you want to change(for example, 

savedir). 

Ali toggle attri butes are set by speci fyi ng on /off. 

Theshow_author attri bute is specified by a number from thefollowing range: o=none, i=username, 2=network address, 
3=both. 

Thesort_art_type attri bute is specified by a number from thefollowing range e=none, i=subject descendi ng, 2=subject 
ascendi ng, 3=from descendi ng, 4=from ascendi ng, 5=date descendi ng, 6=date ascendi ng. 

Thepost_proc_type attri bute is specified by a number from thefollowing range: 8=none, i=unshar, 2=uudecode, 
3=uudecode& list zoo archi ve, 4=uudecode& extraetzoo archive 5=uudecode& list zip archive, 6=uudecode& extraetzip 
archi ve. (If running on AmigaDOS, the zoo optionsarereplaced by their correspondingiha archi ver options.) 

AUTOMATIC KILLAND SELECTION 

When there isa subject or an author that you areeither very interested in, or find completely uninteresting, you can easily 
instruct tin to autoselect or autokill articles with specific subjectsor from specific authors. Theseinstructionsarestored in a 
km file. 



This menu isaccessed by pressing "Kat the group and page levels. It allows the user to kill or select an article that matches 
thecurrent "Subject:" line, "From:" line, or a stri ng entered by the user. The user-entered stri ng can beapplied to the 
"Subject:" or "From:" linesof an article. The km description can belimited to thecurrent newsgroup or it can apply to ali 
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newsgroups. Onceentered, the user can abortthecommand and not ave the km descri ption, edit the km file or savethe 
km descri ption. 

On starti ng tm, theuser'skmfile$HOME/.tin/km isread and on entering a newsgroup any km or seiect descri ptions 
are appi i ed. 

Articlesthat match a km descri ption aremarked killed and are not displayed. Articles that match an autoselect descri ption 
aremarked with an * when displayed. 

PO STING ARTICLES 

tin allows posti ng of articles, follow-up to already posted articles, and replying direct through mail to theauthor of an 
arti ci e. 

Use the w command to post an articleto a newsgroup. After entering the post subject, the default editor (such asvi) or the 
editor specified by the$visuAi_ environment variablewill bestarted and the article can beentered. To crosspost articles, 
simply add a comma and thenameof thenewsgroup(s) to the end of the"N ewsgroups:" li ne at the beginningof the article. 
After savi ng and exiting the editor, you areasked if you wish to abort posti ng the article, edit thearticleagain or post the 
articleto the specified newsgroup(s). 

Use the w command to display a history of the articles you have posted. The date the article was posted, which newsgroups 
the article was posted to, and the article's subject line are displayed. 

Usethet/F command to post a follow-up articleto an already posted article. T he f command will copy the text of the 
originai articleinto the editor. The editing procedure is the sameas when posti ngan article with thew command. 

Usether/R command to reply direct through mail to theauthor of an already posted article. Ther command will copy the 
text of the originai articleinto the editor. The editing procedure is the sameas when posti ngan article with thew command. 
After savi ng and exiting the editor, you areasked if you wish to abort sending the article, edit thearticleagain, or send the 
articleto theauthor. 

CUSTOMIZING THE ARTICLE QUOTE STRING 

When posti ng a follow-up to an article or replying direct to theauthor of an arti de vi a e-mail, the text of the article can be 
quoted. The beginningof the quoted text can contai n information about thequoted article (for example, theN ameand the 
M essagelD of the article). To allow for different situations, certain information from the article can beused in thequoted 
stri ng. The following variables are expanded if found in thetinrc variablesinaii_quote_for-mat= or news_quote_format=: 

%a Address (e-mail) 

%d D ate 

%f Full address (%n (%a>) 

%g Groupname 

%m M essage I D 

%n Nameofuser 

For example, 

mail_quote_f ormat=On %D in %G you wrote: 
news_quote_f ormat=In %M, %F wrote: 

would expand when used to: 

On 21 Jul 1992 09:45:51 -0400 in alt.sources you wrote: 

In <abcINN123@anl433.uucp>, Iain Lea (iain@erlm. Siemens. de) wrote: 

MAILING, PIPING, PRINTING, REPO STING, AND SAVING ARTICLES 

The command interface to mail (m), pipe (j), print (o), crosspost (x) and save(s) articles isthesame for easeof use. 

The initial command will ask you to seiect which article, thread, hot (autoselected) regex pattern, tagged articles you wish to 
mail, pipe, and so on. 
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Tagged articles must have al ready been tagged with theT command. Ali tagged articlescan beuntagged by theu untag 
command. 

If regex pattern matching is selected, you are asked to enter a regular expression (for example, to match ali article subject 
linescontaining net News, you must enter *net News*). A ny articles that match theentered expression will bemailed, 
piped, and so on. 

To save articles to a mailbox with thenameof thecurrent newsgroup (for example, Ait.sources) enter = or =<maiibox 
name>when asked forthesavefilename. 

To Save articles in newsgroup name>/<filename> format, enter +<filename>. 

When saving articles, you can specify whether thesaved filesshould bepost processed (such asunsnar sheii arcmve, 
uudecode multiple parts, and so on). A default process type can beset by theProcesstype in the m Opti ons menu. 

AUTOMATIC MAILING AND SAVING NEW NEWS 

tm allowsnew/unread news articles to bemailed (-m option)/saved (-s option) in batch mode for later reading— useful 
when goingon holiday and you don'twantto return and find that expire hasremoved a wholeload of unread articles. It's 
best to run from crontab every day whileaway, after which you will bemailed a report of which articles were mai led/saved 
from which newsgroupsand the total number of articles mai led/saved. Articlesaresaved in a private news structure under 
your <savedir> directory (default is $HOME/News). 

Becareful of usingthisoption if you read a lotof groupsbecauseyou could overflowyourfilesystem. If you only wantto 
save a few groups, itwould be bestto back up your full $home/. newsrc and create a new onethat only contai ns the 
newsgroupsyou wantto mail/save. Saved news can beread later by tir, -r. 

tin -m iain -c -t newsrc . mail M ali any unread articles in newsgroups specifi ed i n file newsrc . man 
tin -s -c -t newsrc. save Save any unread articles in newsgroups specified in file newsrc . save 

tin -r Read any articles saved by tin -s 

SIGNATURES 

tin will recognize a signature in either $home/ .signature or $home/ .sig. If $home/. signature exists, then the signature 
will bepulled into the editor for mail commands. A signature in $home/. signature will not bepulled into the editor for 
posti ng commands becauseinews will append the signature itself. 

A signature in $HOME/.sig will bepulled into the editor for both posti ng and mailing commands. 
Thefollowing isan example of a $HOME/.sig file: 

NAMES Iain Lea iain.lea@erlm.siemens.de 

SNAIL Bruecken Strasse 12, 8500 Nuernberg 90, Germany 

PHONE +49-911-331963 (home) +49-911-3089-407 (work) 

tin also hasthecapability to generate random signatureson a per-newsgroup basisif so desi red. The wayto accomplish this 
isto specify the default signature or the group attributesigfileas a directory. If, for example, the si gfi le path is/usr/iain/ 
.sigs and .sigs is a directory, then tin will sei ect a random signature from any fi le that is in the directory .sigs (note one 
signature per numbered file). A random signature can also consist of afixed part signature that can contain your name, 
address, and so on, followed by the random sig. Thefixed part of the random sig isread from thefile$HOME/.sigfixed. 

EN VIRO N M EN T VARIABLES 

tinrc D efine this variableif you wantto specify command-lineoptionsthat tin should bestarted with to 

savetyping them each timeit isstarted. Thecontentsof theenvironment variableareadded to the 
front of thecommand-lineoptionsbeforeit isparsed, thereforeallowingan option specified on the 
command lineto override the same option specified in theenvironment. 

tin_homedir D efi ne thi s vari able if you do notwantthe .tin directory in $HOME/.tin. For example, if you want 

ali tin's private fi les in /tmp/ .tin, you would set tindir to /tmp. 
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D efi nethis variable if you do notwantthe .index directory in $HOME/.tm/. index. For example, 

if you want ali tin's i ndex files i n /tmp/ . index, you would set tin_indexdir to /tmp. 

D efi nethis vari ableif you wantto overridethei_iBDiR path thatwas compi led into the tin binary 

viatheMakefile. 

D efi nethis vari ableif you wantto overridethespooLDiR path thatwas compi led into the tin 
binary viatheMakefile. 

D efi nethis vari ableif you wantto overridetheNovRooTDiR path thatwas compi led into the tin 
binary viatheMakefile. 

D efi nethis vari ableif you wantto overridetheLiBDiR/active path thatwas compi led into the tin 
binary viatheMakefile. 

Thedefault N NTP server to remotely read newsfrom. Thisvariableonly needsto beset if the -r 

command-lineoption isspecified and the fi le /etc/nntpserver does not exist. 

Set the article header field "Distri bution:" to the contents of the variable i nstead of thesystem 

default. 

Set the article header field "0 rganization:" to the contents of the variable instead of thesystem 
default. This variable has precedence over thefile$H0ME/ . tm/organization that may al so contain 
an organization stri ng. If you arereading newson an Apollo D ornai nOS machine, theenvironment 
variable newsorg has to beused instead of organization. 

Set the article header field "Reply-To:" to the return address specified by thevariable This isuseful 
if the machine is not regi stered in theU UCP mail mapsor if you wish to receive replies at a 
different machine. Thisvariable has precedence overthefile$HOME/.tin/repiyto that may also 
contain a return address. 

Thiscan contain an address to append to the return address when replying d i recti ythrough mail to 
somebody whosemail address is not di rectly recognized bythelocal host. For example say the 
return address isuser@bigvax, but bigvax isnot recognized by your host, so therefore the mail 
will not reach user-. But the host nttevax isknown to recognizeyour host and bigvax, so if 

ADDADDRESS ÌS Set (for example, setenv ADD_ADDRESS raiittevax for csh Or 
set ADD_ADDRESS (alittevax 

and export add_address for sn), theaddress 

user@bigvax@littlevax will beused and the mail will reach useriabigvax. 

This vari abl e has precedence over the fi le 

$HOME/ . tin/add_address 

that may also contain an address. 

If theBCommand bug report mail address isnot correct, this variable should be setto the correct 
mail address. This variable has precedence over the fi le 

$HOME/ . tin/bug_address 

that may also contain a mail address. 

This variable has precedence over thedefault mailer that isused in ali mailing operations within 
tin (for example, replying rR, and bug reports b). 

Thisvariablehasprecedenceoverthedefaulteditor (for example, vi) thatisused in ali editing 
operations within tin (for example postingw, replying rR, follow-upsfF, and bug reportSB). 
tin i nterprets thisvariable simi larly to rn. It containsa list of patterns, separated by commasand 
possi bly prefixed with exclamation points. A new group ischecked against the list of patterns; if it 
matches, tin subscribestheuserto the group without further query. An exclamation point negates 
themeaningof a match on this pattern and can beused to cancel certain matches. For example, 
setti ng autosubscribe=coihp. os. unix.*, talk.*, ! talk . poiitics . * wi II automati cally subscribe 
the user to ali newsgroupsin the comp.os. unix hierarchy, and ali talk groups other than 
talk. poiitics groups(which will bequeried for as usuai). 
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autounsubscribe tin i nterprets thi s variable si mi larly to m. It is handled liketheAUTosuBscRiBE variable, but 
groups matching the list areunsubscribed from withoutfurther query. For example, setti ng 
AUTouNsuBscRiBE=ait . f lame . * , u* , ! u k , * wi 1 1 automati cai ly unsubscribe the user from ali new 
alt. f lame groupsand ali groups starti ng with u (university groups) other than uk groups (which 
will bequeried for as usuai). 

TIPSAND TRICKS 

tm can pretty much benavigated by using thefour cursor keys. Theleft-arrow key goesup a leve!, theright-arrow key goes 
down alevel, theup-arrow key goesup a li ne (or page, at article Viewer level) and thedown-arrow key goes down a line (or 
page, at arti ci e Viewer level). 

Thefollowing newsgroups provide useful informati on concerni ng news software: 

- - news, software, readers Information about news user agents tm, m, nn, vn, and so on 

- - news, software. nntp Information about N NTP 

- -news.software.b Information about newstransport agents Bnews, cnews, and inn) 

- -news.answers Frequently asked questions(FAQs) about many different themes 

Manyprompts (for example, Mark everything as read? (y/n) :) within tin offer a default choice that the cursor is 
positioned on. W hen you press <CR>, the default valueistaken. 

M any prompts (for example, Post subject [ ]>) within tm can beaborted by pressing <ESC >. 
When tm isrun in an xterm window, itwill resizeitself each timethe xterm isresized. 
tin will reread theactivefileat set intervalsto show any newly arrived news. 

xterm BUTTONS 

lf the environment variable terni i s set to xterm, then button pressing can beused to select groupsand arti cles. 

In the Group Selection menu, if the mouse is poi nting beforethegroup'slisting region, the previous page is sei ected (just 
likeb). If the mouse is poi nting after the group's listi ng region, thenext page is sei ected (just li ke space). If the mouse is 
poi nting at agroup, then 

Left button M ovesto thegroup pointed at 

Other buttons M oveto and select thegroup pointed at, just I i ke <cr> 

In the Article menu, if the mouse is poi nting before the article li sting region, the previous page is sei ected (just likeb). If the 
mouse is poi nting after the article li sting region, thenext page is sei ected (just li ke space). If the mouse is poi nting at an 
article, then 

Left button M ovesto the arti de pointed at 

Center button Readsnextunread arti de from that pointed at, just li ke <tab> 
Right button Reads article pointed at, just like <cr> 

In theThread menu, if the mouse is pointing before the arti de listi ng region, the previous page is sei ected (just likeb). If the 
mouse ispointing after the article listing region, thenext page is sei ected (just like space). If the mouse is pointing at an 
article then 

Left button M ovesto the arti de pointed at 

Center button Reads next unread arti de from that pointed at, just like <TAB> 
Right button Reads article pointed at, just like <CR> 

In the Spool Selection menu, if the mouse ispointing before the spool listing region, the previous page i s sei ected (just like 
b). If the mouse ispointing after the spool listing region, thenext page is sei ected (just like space). If the mouse is pointing 
at a spool selection, then 



tin, rtin, cdtin, tind 




Leftbutton M ovesto the spool poi nted at 

Other buttons M oveto and select the spool pointed at, just like <cr> 

In other menusand areas, button pressing reverts back to usuai cut and paste of xterm, but after one click of any button. 
FILES 



$H0ME/ . newsrc 


Subscribed to newsgroups 


$HOME/ . newsauth 


nntpserver password pairsfor N NTP serversthat requireauthorization 


$HOME/.tin/tinrc 


Options 


$HOME/.tin/attributes 


C ontains user-specifi ed group attributes 


$HOME/.tin/ .index 


N ewsgroups index files directory 


$HOME/.tin/ .mailidx 


M ailgroups index files directory 


$HOME/ . tin/ .saveidx 


Saved newsgroups index files directory 


$HOME/ . tin/active.mail 


Acti ve fi le of users mai Igroups 


$HOME/ . tin/active . save 


Acti ve fi le of users saved newsgroups 


$HOME/.tin/add_address 


Address to add to when replyingthrough mail 


$HOME/ . tin/bug address 


Address to send bug reportsto 


$HOME/.tin/kill 


Artide kill and autoselection file 


$HOME/ . tin/organization 


Stringto replace default organization 


$HOME/.tin/posted 


H i story of articles posteci by user 


$HOME/.tin/replyto 


H ost address to use in "Reply-To:" mail header 


$HOME/ . signature 


Signature 


$HOME/.Sig 


Signature 


$HOME/ . sigf ixed 


Fixed part of a randomly generated signature 


/usr/lib/news/motd 


N ews message-of-the-day file 


/usr/lib/news/newsgroups 


Short description of ali newsgroups 


/usr/lib/news/subscriptions 


List of newsgroups to subscribe fi rst-time user to 



BUGS 

There are bugssomewhereamong thecreepingfeaturism. Any bugsfound should bereported by theB (bug report) 
command. 

Coredumpswhen setti ngcertain toggle options from the Options menu at arti ci e Viewer level. 
Coredumpswhen killing last articlein athread at article Viewer level. 

HI STORY 

Based on thetass newsreader thatwasdeveloped by Rich Skrenta and posted to ait.sources in M arch 1991. tass was 
itself heavily influenced by notes, which was deve! oped at theU niversity of Illinois by Ray Essi ck and Rob Kolstad in 1982. 

vi .0 pl0 (full) was posted in eight partsto ait.sources on 23 Aug 1991. vi .0 pli (full) was posted in eight partsto 
ait.sources on 03 Sep 1991. vi .0 pl2 (full) was posted in ni ne partsto ait.sources on 24 Sep 1991. vi .0 pl3 (patch) 
was posted in four partsto ait.sources on 30 Sep 1991. vi .0 PL4 (patch) was posted in two partsto ait.sources on 02 
Oct 1991. vi .0 PL5 (patch) was posted in four partsto ait.sourceson 17 Oct 1991. vi .0 pl6 (patch) was posted in fi ve 
partsto ait.sources on 27 N ov 1991. vi .0 PL7 (patch) was posted in two partsto ait.sources on 27 N ov 1991. vi .1 
plo (full) was posted in eleven partsto ait.sources on 13 Feb 1992. vi .1 pli (full) was posted i n twelve parts to 
ait.sources on 24 M ar 1992. vi .1 pl2 (patch) was posted in four partsto ait.sources on 30 M ar 1992. vi .1 pl3 (full) 
was posted in fifteen partsto ait.sources on 13 M ay 1992. vi .1 pl4 (full) was posted in fifteen partsto ait.sources on 
22 Jun 1992. vi .1 pls (patch) was posted in seven partsto ait.sourceson 11 Aug 1992. vi .1 pl6 (full) was posted in 
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fifteen partsto ait.sources on 14 Sep 1992. vi .1 plz (patch) wasposted in ten partsto ait.sources on 15 N ov 1992. 
vi .1 pls (patch) wasposted in six partsto ait.sources on 06 Dee 1992. vi .1 pl9 (patch) wasposted in th ree partsto 
ait.sources on 20 M ar 1993. vi .2 plo (full) wasposted in fourteen partsto ait.sources on 25 M ay 1993. vi .2 pli 
(patch) wasposted in eight partsto ait.sources on 14 J ul 1993. vi .2 pl2 (patch) wasposted in partsto ait.sources in 
September 1993. 
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tload 

tioad— Graphic representation of system load average 
SYNOPSIS 

tload [-s scal e ] [-d del ay ] [tty ] 

D ESC RIFIO N 

tioad prints a graph of thecurrent system load average to thespecified tty (or the tty of the tioad processif noneis 
speci fi ed). 

OPTIONS 

The -s scaie option allows averti cai scale to bespecified for the di splay (in characters between graph ticks); thus, asmaller 
value represents a larger scale, and viceversa. 

The -d deiay setsthedelay between graph updatesin seconds. 
FILES 

/proc/ioadavg Load average informati on 

SEEALSO 

ps(l), top(l), uptime(l), w(l) 

BUGS 

The -d deiay option sets the ti me argument for an aiarm(2); if -d a isspecified, thealarm isset to 0, which will never send 
the sigalrm and update thedisplay. 

AUTHORS 

Branko Lankester, David Engel (david@ods.com), and M ichael K. Johnson (johnsonm@sunsite.unc.edu) 

Cohesive Systems, 20 M arch 1993 

top 

top— D isplay top C PU processes 
SYNOPSIS 

top [ -] [ddel ay ] [q] [S] [s] [i] 

D ESC RIFIO N 

top providesan ongoing look at processor activity in real ti me. It displaysa listing of the most CPU -intensi ve taskson the 
system, and can provide an interactive interface for manipulating processes. 
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COMMAND-LINE OPTIONS 

d Specifi es the delay between screen updates. You can changethiswith thes interactivecommand. 

q Thiscausestop to refresh without any delay. If the Caller hassuperuser privileges, top runswith the highest 

possi blepriority. 

s Specifi es cumulative mode, whereeach processislisted with the CPU timethat it aswell asitsdead children has 

spent. This is like the -s flag to ps(l). See the di scussi on of thes interactivecommand later in thismanual page. 

s Tells top to run in secure mode. This disables the potentially dangersof the interactive commands. (See 

"Interactive Commands," later in thismanual page) A secure top isa nifty thingto leaverunningon a spare 
terminal. 

i Start top, ignoringany idleorzombieprocesses. (Seetheinteractivecommand i.) 

FIELD DESCRIPTIONS 

top displays a variety of i nformati on about the processor state T he di splay is updated every fi ve seconds by default, but you 
can changethatwith thed command-lineoption or thes interactivecommand. 

uptime This li ne displays the time the system has been up, and thethreeload averagesfor the system. Theload 

averagesaretheaveragenumber of process ready to run duri ng the last 1, 5, and 15 mi nutes. This line is 

just like the output of uptime(l). 
processes The total number of processes running at the time of the last update. This is also broken down into the 

number of tasks that are running, sleeping, stopped, orundead. 
cpu states Shows the percentage of C PU timein user mode, system mode, niced tasks, and idle. (N iced tasks areonly 

thosewhosenice value is negati ve.) Ti me spent in niced tasks wi II also becounted in system and user 

time, so thetotal wi 1 1 bemorethan 100 percent. 
Meni Statisticson memory usage, including total availablememory, freememory, used memory, shared 

memory, and memory used for buffers. 
swap Statisticson swap space, including total swap space, availableswap space, and used swap space This and 

Mem arejust like the output of f ree(l). 
pid T he process I D ofeach task. 

user Theusernameof thetask'sowner. 

pri T he priority of the task. 

ni Themce value of the task. N egativemce values are lower priority. 

size T he sizeof the task's code plus data plus stack space, in kilobytes, isshown here 

rss Thetotal amount of physi cai memory used bythetask, in kilobytes, isshown here. 

shrd T he amount of shared memory used bythetask isshown in thiscolumn. 

st T he state of the task isshown here. The state i sei ther s for sleeping, d for uni nterruptible sleep, r for 

running, z for zombie, or t for stopped or traced. 
time Total CPU timethetask hasused since it started. If cumulative mode ison, this also includestheCPU 

ti me used by the process's children that havedied. You can set cumulative mode with thes command-l ine 

option ortoggleitwith the interactive commands. 
%cpu Thetask'sshareof theCPU timesincethe last screen update, expressed as a percentage of total CPU time. 

%mem Thetask'sshareof the physi cai memory. 

command T he task's command name, which will betruncated if it istoo longto bedisplayed on oneline. Tasks in 

memory will haveafull command line, but swapped-out tasks will only have the nameof the program in 
parentheses, for example, (getty). 

INTERACTIVE COMMANDS 

Several single-key commands are recognized whiletop is running. Some are disabled if thes option has been given on the 
command line. 




" l E rases an d red raws th e screen . 

h or ? D isplays a help screen givi ng a bri ef summary of commands, and the status ofsecu re and cumulative modes. 
k Kill a process. You will beprompted forthepiD of the task, and the signal to send to it. For a normal kill, send 

signal 15. Forasure, but rather abrupt, kill, send signal 9. The default signal, aswith kiii(l), is 1 5 , sigterm. 

Thiscommand is not avai lable in securemode. 
i Ignore idle and zombie processes. T his is a toggle switch. 

n or# Changethenumber of processesto show. You will beprompted to enter thenumber. Thisoverridesautomatic 
determination of thenumber of processesto show, which isbased on window sizemeasurement. If 0 isspecified, 
then top will show as many processes as will fit on the screen; this isthe default. 

q Quit. 

r Reni ce a process. You will beprompted for the piDof the task, and thevalueto niceit to. Entering a positive 

valuewill cause a process to beniced to negative vai ues, and losepriority. If root isrunningtop, a negative value 
can beentered, causi ng a process to get a higher than normal priority. The default renice value is 10. This 
command is not avai lable in securemode. 

s Thistogglescumulativemode,theequivalentof ps -s, in otherwords, thatCPU timeswill include a process's 

defunct children. For someprograms, such as compi lers, which work by forking into many separate tasks, normal 
mode will makethem appear less demandi ng than they actually are. Forothers, however, such as shells and init, 
this behavior iscorrect. In anycase, try cumulative mode for an alternative vi ew of CPU use. 

s Changethedelay between updates. You will beprompted to enter the delay time, in seconds, between updates. 

Fractional valuesarerecognized down to microseconds. Entering 0 causes conti nuous updates. The default value 
is 5 seconds. N otethat low values cause nearly unreadably fast displays, and greatly raisetheload. Thiscommand 
is not avai lable in securemode. 

NOTES 

Thisproc-based top worksby readingthefilesin theproc filesystem, mounted on /proc. If /proc isnot mounted, top will 
not work. 

%cpu showsthecputime/realtimepercentagein the peri od of ti me between updates. For the first update, a short delay is 
used, and top itself domi nates the CPU usage. After that, top will drop back, and amorereliableestimateof CPU usageis 
avai lable. 

ThesizE and rss fields don't count the page tables and the task struct of a process; thisisat least 12K of memory that is 
alwaysresident. size isthevirtual sizeof theprocess(code+data+stack). 

Keep in mind that a process must die for itstimeto berecorded on itsparent by cumulative mode. Perhapsmoreuseful 
behavior would beto follow each process upwards, adding time but that would bemoreexpensive, possibly prohibitively so. 
In anycase, that would maketop's behavior incompatiblewith ps. 

SEEALSO 

ps(l), f ree(l), uptime(l), kill(l), renice(l). 

BUGS 

If the window is less than about 70x7, top will not format informati on correctly. 
AUTHOR 

top wasoriginally written by Roger Binns, based on Branko Lankester's(iankeste@fwi.uva.ni) ps program. Robert N ation 
(nation§rocket. sanders.iockheed.com) rewroteit signifi cantly to use the proc filesystem, based on M ichael K. Johnson's 
(johnsonm@sunsite.unc.edu) proc-based ps program. M any changes were made, including secure and cumulative modes 
and ageneral cleanup, by M ichael Shields (mjshieid@nyx.es. du.edu). 

Linux, 1 February 1993 
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touch 

t o uc h— C han ge f i I e ti m estam ps 
SYNOPSIS 

touch [-acfm] [ -r r ef e r e ne e- f il e ] [ -t MMDDhhmm[ [CC]YY] [ .ss] ] [ - d t i me ] 

[ - -time={at i me , access, use, intime, modify}] [ - - date=t i me ] [ - -f ile=r ef e r e ne e- f i I e ] 

[--no-create] [--help] [--version] file... 

D ESC RIPTIO N 

Thismanual page documents the GN U version of touch, touch changes the access and modification timesof each given file 
to thecurrent ti me. Filesthat do not exist arecreated empty. If the first fi lename given would bea vai id argument to the-t 
option and no timestamp is given with any of the -d, -r, or -t optionsand the - - argument is not given, that argument is 
interpreted as the time for the other files in stead of as a f i I en am e. 

If changing both the access and modification ti mesto thecurrent time, touch can changethetimestampsfor files that the 
user running it does not own but haswritepermission for. Otherwise, the user must own the files. 

OPTIONS 

-a, - -time=at i me, 

- - time=a c c e s s , 

- -time=u s e 
-c, - -no-create 
-d, - - date t i me 

-f 

-m, - -time=mt i me, 

- - time=mo d i f y 
-r, - -file reference-fi I e 
-t MMDDhhnim[ [CC]YY][.ss ] 

- - help 
• -version 

GNU F i le U ti I i ti es 



Changetheaccesstimeonly. 

Do not create files that do not exist. 

Uset i me (which can bein various common formats) instead of thecurrent ti me 1 1 can 
contain month names, timezones, am and pm, and so on. 
Ignored; for compati bility with BSD versionsof touch. 
Change the modification timeonly. 

Use the timesof r ef er enee - f i i e instead of thecurrent time. 

U se the argument (months, days, hours, minutes, optional century and years, optional 

seconds) instead of thecurrent time. 

Printausagemessageon standard output and exit successfully. 

Print version informati on on standard output, then exit successfully. 



tr 

tr— Translate or delete characters 
SYNOPSIS 

tr [-est] [--complementi [ - -squeeze-repeats] [ - -truncate-set1 ] stringi stri n g 2 
tr f -s, - -squeeze-repeatsg [-c] [--complementi stringi 
tr f -d, - -deleteg [ -c] stringi 



tr f-d, --deleteg f-s, - -squeeze-repeatsg [-c] [--complementi stringi stri r g 2 
GNU tr also accepts the - -heip and - -version Options. 



tr 



D ESC RIFIO N 

Thismanual page documents the GN U version oftr.tr copies the standard inputto the standard output, perforimi ngone 
of thefollowing operations: 

■ Translate and optionally squeeze repeated characters in theresult 

■ Squeeze repeated characters 

■ Delete characters 

■ D elete characters, then squeeze repeated characters from the result. 

Thest ri ngi and (if given) stri n g 2 arguments define ordered setsof characters, referred to below asset 1 and set 2. These 
sets are the characters of the input thattr operateson. The - -compiement (-c) option replaces seti with itscomplement (ali 
of the characters that are not i n s e 1 1 ). 

SPECIFYING SETSOF CHARACTERS 

Theformatof thest ri ngi and stri n g 2 arguments resemblestheformatof regularexpressions; however, they arenotregular 
expressions, only listsof characters. M ost characters simply representthemselvesin these stri ngs, but the stri ngscan contain 
theshorthandsin thefollowing list, for convenience. Someof them can beused only in st r i ngi or st r i n g 2 , as noted. 

Backslash escapes. A backslash followed by a character not listed causes an errar message. 

\a Control-G 
\b Control-H 
\f Control-L 
\n Control-J 
\r Control-M 
\t Control-I 
\v Control-K 

\ooo The character with thevalue given by 000, which isl to 3 octal digits 
\n A backslash 

Ranges. The notati on m-n expandsto ali of the characters from m through n, in ascendi ng order. m should collate before n; if 
it doesn't, an errar results. Asan example, 0-9 isthesameas 0123456789. Although GN U tr does not support the System 
V syntaxthat uses square brackets to enclose ranges, translati onsspecifi ed in that format wi II stili work as long as the brackets 
in st r i ngi correspond to i denti cai brackets in st r i n g 2 . 

Repeated characters. The notation [c*n] instri n g 2 expandston copies of character c.Thus, [y*6] isthesameasyyyyyy. 
The notati on [c*] in stri n g 2 expandsto asmany copies of c asareneeded to makeset 2 as long ass e 1 1 . 1 f n beginswith a 
0, itisi nterpreted in octal, otherwisein decimai. 

Character classes. The notation [ : class -name: ] expandsto ali of the characters in the(predefined) class named class - 
name. The characters expand in no particular order, except for the upper and ìower classes, which expand in ascending 
order. When the - -delete (-d) and - - squeeze- repeats (-s) opti ons are both given, any character class can beused in 
stri n g 2 . Otherwise, only the character classes ìower and upper areaccepted in st r i n g 2 , and then only if thecorresponding 
character class (upper and ìower, respectively) isspecified in the same relative position i n s t r i n g 1 . D oing this specifies case 
conversi on. The class names are given in thefollowing list; an errar results when an invai id class name is given. 

ainum Letters and digits 

alpha Letters 

biank H orizontal whitespace 

entri Control characters 

digit Digits 

graph P ri ntabl e eh aracters, not includi ng space 

ìower Lowercase letters 
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print 


Printablecharacters, includi ng space 


punct 


Punctuation characters 


space 


Horizontal or vertical whitespace 


upper 


U ppercase letters 


xdigit 


H exadecimal digits 



Equivalenceclasses. The syntax [=c = ] expandsto ali of the characters that areequivalent to c, in no parti cu larorder. 
Equivalenceclasses are a recent invention intended to support non-English alphabets. Butthereseemsto beno standard way 
to definethem or determi ne their contents. Therefore, they arenot fully implemented in GN U tr; each character's 
equivalence class consists only of that character, which makes thisauselessconstruction currently. 

TRAN SLATIN G 

tr performs translati on when stri n g 1 and stri n g 2 areboth given and the - -delete (-d) option isnotgiven.tr translates 
each character of its input that isin set 1 to the corresponding character in set 2 .Characters not in set 1 arepassed through 
unchanged. When a character appears morethan once in set 1 and the corresponding characters in set 2 arenot ali thesame, 
onlythefinal oneisused. Forexample, thesetwo commands areequivalent: 

tr aaa xyz 
tr a z 

A common useof tr isto convert lowercase characters to uppercase. Thiscan bedonein many ways. H erearethreeof them: 

tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 
tr a-z A-Z 

tr 1 [ :lower: ] 1 1 [ :upper: ] 1 

When tr isperforming translati on, seti and set 2 should normally nave thesame length. If set 1 isshorter than set 2, the 
extra characters at the end of s e 1 2 are ignored. 

On theother hand, makingset 1 longer than set 2 isnot portable; PO SI X. 2 says that the result isundefined. In this 
situation, the BSD trpadsset2 tothelength ofseti by repeating the last character of set 2 asmany timesasnecessary.The 
System V tr truncatesset 1 to the length of set 2. 

By default, GN U tr handles this case like the BSD tr does. W hen the - -truncate-seti (-t) option is given, GN U tr 
handles this case li ke the System V tr instead. This option is ignored for operationsother than translation. 

Acting like the System V tr in thi s case breaks the relati vely common BSD idiom: 

tr -cs A-Za-z0-9 ' n01 2 ' 

because it converts only zero bytes (the first element in the complementof seti), ratherthan ali nonalphanumerics, to 
newlines. 

SQUEEZING REPEATSAND DELETING 

When given just the - -delete (-d) option, tr removesany input characters that are in set 1. 

When given just the - -squeeze-repeats (-s) option, tr replaceseach input sequence of a repeated character that is in set 1 
with a si ngle occurrence of that character. 

When given both the - -deiete and the - - squeeze-repeats options, tr first performs anydeletionsusing set i, then 
squeezes repeats from any remai ni ng characters using s et 2 . 

The - - squeeze-repeats option may also beused when translati ng, in which casetr first performs translation, then squeezes 
repeats fra m any rem ai n i n g eh aracters usi n g s e 1 2 . 

H ere are some examples to i llustrate various combinations of options. 



tS6t r reSSt 




Remove ali zero bytes: 

tr -d ' n000 ' 

Put ali wordson linesby themselves. T his converts ali nonalphanumeric charactersto newlines, then squeezeseach stri ng of 
repeated newlines into a single newline: 

tr -cs 1 [a-zA-Z0-9] 1 1 [nn*] 1 

Convert each sequenceof repeated newlines to a single newline 

tr -s 'nn' 

GNU tralso accepts the following optionsin any combinati on with theothers. 
- -heip Print ausagemessageand exit with a non-zero status, 

--version Print version information on standard output, then exit. 

WARNING MESSAGES 

Setting the environment vari ableposixLY_coRRECT turnsoff several warning and errar messages, for stri et compii ance with 
POSIX.2. Themessagesnormally occur in the following circumstances: 

1. When the - -deiete option isgiven but - -squeeze-repeats isnot, and st ri n g 2 isgiven, GN U tr by default printsa 
usagemessageand exits, becausest r n g 2 would not beused. T he posix specification saysthat st r n g 2 must beignored 
in thiscase. Silently ignori ng argumentsisa bad idea. 

2. When an ambiguousoctal escape isgiven. For example, n400 isactually n40followed by the digit 0, becausethevalue 
400 octal does not fit i nto a si ngle byte. 

N otethat GN U tr does not provide complete BSD or System V compati bi lity. For example, there isno option to disable 
interpretation of the POSIX construets [ : alpha : ], [=o=], and [o*ib]. Also, GN U tr does not delete zero bytes automati - 
cai ly, unlike traditional UN IX versions, which provide no wayto preserve zero bytes. 

GNU Text Utilities 

tset, reset 

tset, reset— Terminal initialization 
SYNOPSIS 

tset [-IQrs] [-t] [-e eh] [-i eh] [-k eh] [-m mapping] [terminal] 
tset -h 
tset -V 

reset [-IQrs] [-t] [-e eh] [-i eh] [-k eh] [-ni mapping] [terminal] 
reset -h 
reset -V 

D ESC RIPTIO N 

tset initializes termi nals. tset first determ ines the typeof terminal that you are usi ng. T his determi nati on isdoneas 
follows, usingthefirst terminal typefound: 

■ Theterminal argument specified on thecommand line 

■ The vai ue of the term environmental variable 

■ Theterminal type associ ated with the standard errar output device in the /etc/ttytype file 

■ Thedefaultterminal type, unknown 
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If the terminal typewas not specified on thecommand line, the -m option mappingsarethen applied (seethefollowing 
section, "Options," for more informati on). Then, if the terminal type begins with a question mark (?), the user isprompted 
for confi rmation of the terminal type. An empty response confi rms the type, or, anothertypecan beentered to speci fy a new 
type. After the terminal type hasbeen determined, thetermcap entry for the terminal is retri eved. If no termcap entry is 
found forthetype, theuser isprompted for another terminal type. 

After thetermcap entry isretrieved, thewindow size, backspace, interrupt, and line ki II characters (among many other 
things) are set and theterminal and tab i n iti al izati on stri ngs are sent to thestandard errar output. Final ly, if the erase, 
interrupt, and linekill characters havechanged, or are not set to their default values, their values are displayed to thestandard 
error output. 

When invoked as reset, tset setscooked and echo modes, turnsoff cpreak and raw modes, turnson newli ne translati on and 
resetsany unset special characters to their default values beforedoing the terminal initialization described above Thisis 
useful after a program dies leaving a terminal in an abnormal state. N ote you may haveto type<i_F>reset<i_F> (the li ne-feed 
character is normally control -j) to get theterminal to work, as carri age- return may no longer work in the abnormal state. 
Also, theterminal will often not echo thecommand. 

OPTIONS 

The options are as follows 

-t Theterminal type is displayed to thestandard output, and theterminal isnot initialized in any way. 
-e Set the erase character to cn. 

-i Do not send theterminal or tab initialization stri ngs to theterminal. 
-i Set the interrupt character to eh. 
-k Set the linekill character to eh. 

-m Specify a mappingfrom a porttypeto a terminal. Seethefollowing section, "Setti ng theEnvironment," for more 
information. 

-r P ri nt theterminal typeto thestandard error output. 

-s Print the sequence of shell commandsto i n i ti al i ze the en vi ron ment vari abl es columns, lines, term, and termcap 

to thestandard output. 
q Don't display any values for the erase, interrupt, and linekill characters. 

-w Force setti ng of display size as defined in /etc/termeap file, 
-h Print short usage message. 
-v Print versi on number. 

Theargumentsforthe - e, -i, and -k options may either beentered asactual characters or by using the hat notati on, for 
example, controi-h may bespecified as" h or * n. 

SETTING THEENVIRONMENT 

It is often desirableto set the terminal type and information about the terminali capabilitiesand display size in the shdl's 
environment. Thisis done with the -s option; when this option is specified, the commandsto enter the information into the 
shell 'senvironment are output to thestandard output. If the shell environmental variableends in csh, the output 
commands are for the csh(l); otherwise, they are for sh(l). N ote, the output commands for the csh set and unset the shell 
variablenogiob. The foli owing line in the .ìogin or .prof ne fileswill initi al ize the environment correctly: 

eval 'tset -s options ... 1 

TERMINAL TYPE MAPPING 

When theterminal is not hardwired into the system (orthecurrent system information isincorrect), theterminal type 
derived from the /etc/ttytype file or the term environmental variableis often somethinggeneric like network, dialup, or 
unknown. When tset isused in astartup script .profile for sn(l) usersor .ìogin for csn(l) users), it is often desirableto 
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provide informati on about thetypeof terminal used on such ports. Thepurposeof the -moption isto map from some set of 
conditionsto a terminal type; that is, to teli tset, "If l'm on thisport at a particular speed, guessthat l'm on that kind of 
terminal." 

Theargumentto the -moption consistsof an optional port type, an optional operator, an optional baud rate speci fi cation, an 
optional colon (:) character, and aterminai type. The port type is a stri ng (deli mited byeither the operator or the colon 
character). The operator may beany combination of: &>, &<, &<?, and &i; &> meansgreater than, &< meanslessthan, &@ 
meansequal to, and &! invertsthesenseof the test. The baud rate is speci fi ed asa number and iscompared with the speed of 
the standard error output (which should be the control terminal). The terminal typeisastring. 

If the terminal typeisnot specified on thecommand line, the -m mappings are appi ied to the terminal type. If the port type 
and baud rate match themapping, the terminal type specified in themapping replacesthecurrent type. If more than one 
mapping is specified, thefirst applicable mapping isused. 

Forexample, consider the followi ng: 

dialup>9600 :vt100 

The port type isdiaiup, theoperator is>, the baud rate speci fi cation ÌS9600, and theterminal typeisvti00 . The result of 
this mapping isto specify that if theterminal typeisdiaiup, and the baud rateisgreater than 9600 baud, a terminal typeof 
vti00will beused. 

If no port type is specified, theterminal type wi II match any port type; forexample, 

-m dialup: vt1 00 -m :?xterm 

wi 1 1 cause any dialup port, regardlessof baud rate, to match theterminal type: 

Vt100, 

and any nondialup port type to match theterminal type: 

?xterm. 

N ote, becauseof theleading question mark, the user wi II bequeried on a default port asto whetherthey are actually usingan 
xterm terminal. 

N 0 whitespacecharactersarepermitted in the -m option argument. Also, to avoid problemswith metacharacters, it is 
suggested that the enti re - moption argument beplaced within single quote characters, and that csn users insert a backslash 
character(\) beforeany exclamation marks(i). 

ENVIRONMENT 

Thetset command utilizes the shell and term environment variables. 
tset can set columns, lines, term, and termcap environmental variables. 

FILES 

/etc/ttytype system Port nameto terminal type mapping database 
/etc/termcap Terminal capabi I ity database 

SEE ALSO 

csh(l), tcsh(l), sh(l),bash(l),stty(l), tty(4), termcap(5), ttytype(5), environ(7) 

HISTORY 

Thetset command appeared in BSD 3.0. 
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COMPATIBILITY 

The - a, -e, -h, -s, -u, and -v options havebeen deleted from the t set utility. N oneof them weredocumented in 4.3BSD 
and ali areof limi ted utility at best. The -a, -d, and -p options are si mi larly not documented or useful, but were retai ned as 
they appear to bein widespread use. It isstrongly recommended that any usageof thesethree options bechanged to use the 
-m option instead. The -n option remai ns, but has no effect. It is stili permissibleto specify the -e, -i, and -k options 
without arguments, although it isstrongly recommended that such usagebefixed to explicitly specify the character. 

Executing tset as reset no longer implies the -q option. Also, the interaction between the - option and the terminal 
argument in some hi storie implementationsof tset hasbeen removed and hasbeen replaced with -t option. 

Finally, the tset implementation hasbeen completely redoneaspart of theaddition to the system of a IEEE Stdl003.1- 
1988 (PO SI X) -com pliant terminal interface and will no longer compile on systemswith older terminal interfaces. 

Linux, 12 January 1995 



tsort 

tsort— Topological sortof adirected graph 
SYNOPSIS 

tsort [file] 

D ESC RIFIO N 

tsort takesa list of pairsof nodenames representi ng directed arcsin a graph and printsthenodesin topological order on 
standard output. Input istaken from thenamed file, or from standard input if no file is gi ven. 

N ode names in the input are separated by whitespace, and theremust bean even number of nodes. 

Presenceof a nodein a graph can be represented by an are from thenodeto itself. Thisis useful when a nodeisnot 
connected to any other nodes. 

If the graph containsacycle(and thereforecannot beproperly sorted), oneof the arcsin thecycleisignored and thesort 
continues. Cyclesarereported on standard errar. 

SEE ALSO 

ar(l) 

HI STORY 

A tsort command appeared in AT&T v7. This tsort command and manual page are derived from sources contri buted to 
Berkeley by M ichael Rendei I of M emori al U niversity of N ewfoundland. 

23 Aprii 1991 

twin 

twin— Tab Window M anager fortheX Window System 
SYNTAX 

twin [ -display dpy ][-s ][-f initfile ][-v ] 

D ESC RIFIO N 

tv™ is a window manager for the X Window System. It provi desti ti ebars, shaped Windows, several formsof icon manage- 
ment, user-defined macro functions, click-to-typeand pointer-driven keyboard focus, and user-specified key and pointer 
button bindings. 
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This program isusually started by theuser'ssession manager or startup script. When used from xdm(l) or xinit(l) without a 
session manager, twm isfrequently executed in theforeground asthelast client. When run thisway, exiting twm causesthe 
session to beterminated (logged out). 

By default, application Windows are surrounded by a "f rame" with atitlebar at the top and a special border around the 
window. Thetitlebar contai ns the window'sname, arectanglethat islitwhen thewindow isreceiving keyboard input, and 
function boxesknown astitlebuttonsattheleftand rightedgesof thetitlebar. 

Pressing pointer Buttonl (usually theleftmost button unlessit has been changed with xmodmap) on atitlebutton will invoke 
the function associated with the button. In the default interface, Windows are iconifi ed by clicking (pressing and then 
immediately releasing) thelefttitlebutton (which lookslikeadot). Conversely, Windows are deiconified by clicking in the 
associated icon or entry in theicon manager. (Seedescription of the variable show- iconiuanager and of the function 

f . showiconmgr.) 

Windows are resi zed by pressing the right titlebutton (which resemblesagroup of nested squares), dragging the pointer over 
theedgethat isto bemoved, and releasing the pointer when the outli ne of thewindow is the desi red size. Similarly, Windows 
aremoved by pressing in thetitleor highlight region, dragging a window outli ne to thenew location, and then releasing 
when theoutlineis in the desi red position. Just clicking in thetitleor highlight region raises the window without moving it. 

When new Windows are created, twm will honor any size and location information requested by the user (usually through - 
geometry command-line argument or resources for the individuai applicati ons). Otherwise, an outlineof thewindow's 
default size, itstitlebar, and li nes di vi di ng the window into a 3x3 grid thattrack the pointer are displayed. Clicking pointer 
Buttonl will position thewindow atthecurrent position and giveit the default size. Pressing pointer Button2 (usually the 
middle pointer button) and dragging the outli ne will gi ve the window itscurrent position but allow the si desto beresized as 
described above. Clicking pointer Button3 (usually the right pointer button) will give the window itscurrent position but 
attempt to make it long enough to touch the bottom of the screen. 

OPTIONS 

twm accepts thefollowing command-line options: 
-display dpy T his option specifies thex server to use. 

-s Thisoption indicates that only the default screen (asspecified by -display or by the display environ- 

mentvariable) should bemanaged. By default, twm will attempt to manageall screenson thedisplay. 

-t f m ename Thisoption specifies the name of the startup fileto use. By default, twin will look in theuser's home 
directory for filesnamed .twmrc.num (wherenum isascreen number) or .twmrc. 

-v Thisoption indicates that twm should print error messageswhenever an unexpected X Errar event is 

received. Thiscan beuseful when debugging appi ications but can bedistracting in regularuse. 

CUSTOMIZATION 

M uch of twm's appearance and behavior can be controlied by providi ng a startup fi le in oneof thefollowing locations 
(searched in orderforeach screen bé ng managed when twm begins): 

$home/ . twmrc. se r e e n number The s c r e e n n u mb e r isa small positive number (for example, o, 1, and so on) 

representi ng the screen number (for example, thelast number in the display 
environmentvariablehost:dispiaynum.screennum) thatwould beused to contact 
that screen of the display. This is intended for displays with multiple screens of 
differì ng visual types. 

$home/. twmrc This is the usuai nameforan individuai user's startup file. 

<xRoot>/iib/xn/twm/system. twmrc If neither of the precedi ng fi les are found, twm will look in this fi le for a default 

confi guration.T his isoften tailored by the site administratorto provide con venient 
menusorfamiliarbindingsfor noviceusers. <xRoot> refersto therootof theXll 
instali tree. 



Parti: U ser Commands 



If no startup filesarefound, twmwill usethe built-in defaults described. Theonly resourceused by twin isbitmapFiiePath 
for acolon-separated list of di rectories to search when lookingfor bitmap files. Formoreinformation, seetheAthena 
W idgets manual and xrdb(l). 

twin startup files are logicai ly broken up into threetypes of specifications: variabies, Bindings, and Menus. The variabies 
section must come first and isused to descri be the fonts, colors, cursors, borderwidths, icon and window placement, 
highlighting, autoraising, layout of titles, warping, and use of the icon manager. TheBindings section usually comessecond 
and isused to specify thefunctions that should beinvoked when keyboard and pointer buttonsarepressed in Windows, 
icons, titles, and frames. The Menus section givesany user-defined menus (contai ni ngfunctionsto beinvoked or commands 
to beexecuted). 

Variable names and keywords are case- in sensi ti ve. Strings must be surrounded by doublé quote characters (for example, 
"blue") and are case-sensitive. A pound sign (#) outside of a string causes the remainder of the line in which thecharacter 
appears to be treated as a comment. 

VARIABLES 

M any of the aspects of twm's user i nterface are control led by variabies that may be set i n the user's startup fi le Some of the 
optionsareenabled or disabled simply by thepresenceof a parti cular keyword. Other optionsrequi re keywords, numbers, 
strings, orlistsof ali of these. 

Lists are surrounded by bracesand are usually separateci by whitespaceor a newline. For example, 

AutoRaise { "emacs" "XTerm" "Xmh" } 

or 

AutoRaise 
{ 

"emacs" 
" XTerm" 
"Xmh" 

} 

When a variable contai ni ng a list of strings representi ng Windows issearched (for example, to determi ne whether or not to 
enableautoraise, asshown in the precedi ng example), a string must bean exact, case- sensi ti ve match to thewindow's name 
(given bytne wm_name window property), resourcename, or class name (both given by thewM__cLAss window property). The 
precedi ng example would enableautoraiseon Windows named emacs aswell asany xterm (becausethey are of class XTerm) or 
xmh Windows (which are of class xmh). 

String argumentsthat areinterpreted asfilenames(seepixmaps, cursors, and iconDirector-y in thefollowing list of 
variabies) will prepend the user's directory (specified by the home environment variable) if the first character i s a tilde { ~). I f, 
instead, the first character is a colon (:), the name is assumed to referto oneof the internai bitmapsthat areused to create 
the default titlebars symbols: : xiogo or ideiete (both refer to thex logo), : dot or: iconify (both refer to the dot), : resize 
(thenested squaresused by the resize button), : menu (a pagewith lines), and : question (thequestion mark used for 
nonexistent bitmap files). 

Thefollowing variabies may be specified atthetopof a twm startup file. Listsof Window name prefix strings are indicated by 
wì n - 1 i s t . 0 ptional argumentsareshown in square brackets: 

AutoRaise { win-iist ] This variable specifies a list of Windows that should automatically be raised whenever the 

pointer enters the window. This action can beinteractively enabled or disabled on 
individuai Windows usi ng the function f .autoraise. 

AutoReiativeResize This variable indi cates that dragging out a window size (either when i n i ti al ly sizingthe 

window with pointer Button2 or when resizing it) should notwait until the pointer has 
crossed the window edges. Instead, moving the pointer automatically causes the nearest edge 
or edgesto moveby the sameamount. This al lows the resizing of Windows that extend off 
the edge of the screen. If the pointer is in the center of the window, or if the resize isbegun 



by pressing a ti tlebutton, twmwill stili wait for the poi nter to crossawindow edge(to 

prevent accidents). Thisoption is parti cularly useful for peoplewho li ke the press- 

drag-release method of sweepi ng out window sizes. 
Bordercoior st r i ng T his variable specifies the default color of theborder to beplaced around ali noniconified 

Windows, [{ wincoioriist }] and may only be given withi n a color, Grayscaie, or Monochrome list. The optional 

wincoioriist specifies a list of window and color namepairsfor speci fying parti cular 

border colorsfor differenttypesof Windows. For example: 

BorderColor 

"gray50" 

{ 

"XTerm" "red" 
"xmh" "green" 
} 

Thedefault isbiack. 

BorderTiieBackground T his variable specifies the default background color in thegray pattern used in st ri ng [{ 
wi ncoi ori i st }] unhighlighted borders(only if NoHighiignt hasn't been set), and may only be given withi n 

a Color, Grayscaie, Or Monochrome list. The Optional wincolorlist allOWS per-windOW 

colorsto be specified. T he default iswnite. 
BordeniieForeground T his variable specifies the default foreground color in thegray pattern used in unhighlighted 
stri n g [{wincolorlist }] borders (only if NoHighiignt hasn't been set), and may only be given withi n a color, 

Grayscaie, Or Monochrome list. The Optional wincolorlist allOWS per-windOW COlorstO be 

specified. Thedefault isbiack. 
Borderwidth pi xei s T his variable specifies the width in pixelsof the border surrounding ali clientwindow 

frames if ciientBorderwidth hasnot been specified. Thisvalueisalso used to set the 

border sizeof Windows created by twm (such astheicon manager). Thedefault is 2. 
Buttonindent pi xei s This variable specifies the amount by which ti ti ebutto nsshould beindented on ali sides. 

Positive values cause the buttonsto be smallerthan thewindow textand highlight area so 

that they stand out. Setti ng this and theTitieButtonBorderwidth variablesto 0 makes 

ti ti ebutto nsas tali and wideas possible. Thedefault isi. 
ciientBorderwidth This variable indicates that border width of awindow'sframeshould be setto the initial 

borderwidth of thewindow, rather than to the valueof Borderwidth. 
color { coiors-Mst } T his variable specifies a list of color assignments to be made if the default display is capable 

of displaying more than simple black and white. Thecoi or s- 1 i st ismadeup of the 

following color vari ables and their values: 

DefaultBackground 
Default Foreground 
MenuBackground 
MenuForeground 
MenuTitleBackground 
MenuTitleFo reground 
MenuShadowColor 
Pointer Foreground 
PointerBac kg round 

Thefollowing color vari ables may also be given a list of window and color namepairsto 
allow per-window colorsto be speci fi ed (seeBordercoior for details): 

BorderColor 
IconManagerHighlight 
BorderTitleBackg round 
BorderTitleFor eground 
TitleBackground 
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TitleForeground 
IconBackground 
IconForeground 
IconBorderColor 
IconManagerBackg round 
IconManagerForeg round 

Forexample: 

Color 

{ 

MenuBackground "gray50" 

MenuForeground "blue" 

BorderColor "red" { "XTerm" "yellow" } 

TitleForeground "yellow" 

TitleBackground "blue" 

} 

Ali of these color variables may al so be speci fi ed for thewionochrome variable, allowing the 
sameinitialization fileto beused on both color and monochromedisplays. 
constrainedMoveTime This variable specifies the length ottime between button clicksneeded to begin a 

mi i m seconds constrained moveperation. D ouble-clicking withi n this amount of timewhen invoking 

f .move will cause the window to bemoved only in a horizontal or vertical direction. Setti ng 
thisvalueto ovvili disable constrained moves. The default ÌS400 milliseconds. 
cursors {cursor-Mst } T his variable specifies the glyphsthat twm should use for various pointer cursors. Each 

cursor may bedefined either from thecursor font orfrom two bitmap files. Shapesfrom 
the cursor font may be specified di rectly as 

0 c u r s 0 r n a me " string " 

wherecursorname is one of the cursor names listed below, and 5 1 ri ng isthenameof a 
glyph asfound in the fi le: 

<XRoot>/ include/ X1 1 /cursorf ont . h 

(without thexc prefix). If thecursor isto bedefined from bitmap files, thefollowing syntax 
isused instead: 

0 cursorname " i ma g e " "mask" 

Thei mage and mask strings specify the names of files containing the glyph imageand mask 
in bitmap(l) form. The bitmap files are located in the same manner as icon bitmap files. 
T he followingexampleshows the default cursor definitions: 



Cursors 




{ 




Frame 


"top_lef t_arrow" 


Title 


"top_lef t_arrow" 


Icon 


"top_lef t_arrow" 


IconMgr 


"top_lef t_arrow" 


Move 


"f leur" 


Resize 


"fleur" 


Menu 


"sb_left_arrow" 


Button 


"hand2" 


Wait 


"watch" 


Select 


"dot" 


Destroy 


"pirate" 



} 

DecorateTransients This variable indi cates that transient Windows (those contai ni ng a wm_transient_for 

property) should havetitlebars. By default, transientsarenotreparented. 

DefauitBackground string T his variable specifies the background color to beused for sizi ng and information Windows. 
The default iswnite. 
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T his variable specifies the foreground color to beused for sizing and informati on Windows. 
Thedefault isbiack. 

T his variable specifies a list of Windows that should not beiconified window (aswould be 
thecaseif iconifyByunmapping had been set). Thisisfrequently used to force some 
Windows to betreated asiconswhileotherwindowsarehandled by theicon manager. 
This variable indicates that Windows should not beallowed to bemoved off thescreen. It 
can beoverridden by thet .forcemovefunction. 

This variable indicatesthat titlebars should not besqueezed to their minimum sizeas 
described under squeezeTitie below. If the optional window list issupplied, only those 
Windows will be prevented from being squeezed. 

This variable indicates that icon pixmaps specified in theicons variable should overrideany 
client-supplied pixmaps. 

This variable specifies the di stance between thetitlebar decorations(thebutton and text) 
and the wi ndow f rame. The default is 2 pixds 

This variable specifies a listof color assignments that should bemadeif thescreen hasa 
Grayscaie default visual. Seethe description ofcoiors. 

This variable specifies the background color of icons, and may only be specified inside of a 
color, Grayscaie, or Monochrome list. The optional wi n - 1 i st is a list of window namesand 
colorsso that per-window colorsmay be specified. See the Border-coior vari ablefor a 
complete description of thewi n- st .Thedefault iswmte. 
T his variable specifies the color of the border used for icon Windows, and may only be 

specified inside Of a Color, Grayscaie, Or Monochrome list. The Optional wi n - 1 i st isa list 

of window namesand colorsso that per-window colors may be specified. Seethe 
Bordercoior variablefor acomplete description of thewi n- m st .Thedefault isbiack. 
This variable specifies the width in pixelsof the border surrounding icon Windows. The 
default ÌS2. 

This variable specifies the directory that should besearched if abitmap filecannot befound 
in any of the di rectories in thebitmapFiiePath resource. 

This variable specifies the font to beused to display icon nameswithin icons. Thedefault is 

variable. 

This variable specifies the foreground colorto beused when displaying icons, and may only 
be specified inside of a color, Grayscaie, orMonochrome list. The optional win-iist isa 
list of window namesand colorsso that per-window colors may be specified. Seethe 
Bordercoior variablefor a complete descri ption of the w n - i s t .Thedefault isbiack. 
This variable indicates that Windows should beiconified by being unmapped without 
trying to map any icons. This assumes that the user will remap the window through the 
icon manager, thet .warpto function, ortheTwmwindows menu. If theoptional wi n- 1 i st is 
provided, only those windowswill beiconified bysimply unmapping. Windows that have 
both this and theiconManager Dontshow options set may not be accessi bleif no bindingto 
theTwmwindows menu is set i n theuser'sstartup file. 

This variable specifies the background colorto useforicon manager entries, and may only 
be specified inside of acoior, Grayscaie, or Monochrome list. The optional wi n- I i st isa 
list of window namesand colorsso that per-window colors may be specified. Seethe 
Bordercoior variablefor a complete descri ption of thewi n- 1 i st .Thedefault iswmte. 
This variable indicates that the icon manager should not display any Windows. If the 
optional wi n- 1 i st isgiven, only thosewindowswill notbedisplayed. T his vari ableis used 
to prevent Windows that arerarely iconified (such asxciock or xioad) from taking up 
space in theicon manager. 
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IconManagerFont string 

IconManagerForeg round 
string [{ wi n- I i st }] 



IconManagerGeometry 
string [ c o I umns ] 



IconManagerHighlight 

string [ { wi n- I i s t }] 



IconManagers 

{ i c on mgr ■ I i s t } 



T his variable specifies the font to beused when displaying icon manager entries. Thedefault 

ÌS variable. 

This variable specifies the foreground colorto beused when displaying icon manager 
entries, and may be specifi ed only inside of a color, Grayscaie, or Monochrome list. The 
optional wi n- 1 i st is a list of window namesand colorsso that per-window colorsmay be 
specifi ed. SeetheBordercoiorvariableforacompletedescription of the w n-i i st .The 
default isbiack. 

T his variable specifies the geometryof the icon manager window. Thest r i ng argument is 
standard geometry specification that indicates the initial full size of the icon manager. The 
icon manager window isthen broken into coi umns piecesand scaled accordi ng to the 
number of entries in the icon manager. Extra entries arewrapped to form additional rows. 
T he default number of columns is 1 . 

This variable specifies the border colorto beused when highlighting the icon manager entry 
that currently has the focus, and can only be specifi ed inside of acolor, Grayscaie, or 
Monochrome list. T he optional wi n- 1 i st isa I i st of window namesand colorsso that per- 
window colorsmay be specified. See the Border- color variable for a complete descri ption 
of thewi n- 1 i st . Thedefault isbiack. 
This variable specifies a list of icon managersto 
create. Each item in the i c on mg r - 1 i st has the following format: 

0 "wi n ■ n a me " [ * i c o n n a me " ] 
" g e o me t r y " col u mn s 

wherewi nname is the name of the Windows that should beput into this icon manager, 

1 conname is the name of that icon manager window's icon, geometry isa standard geometry 
specification, and c o i umns isthe number of columnsin thisicon manager as descri bed in 

Icon -ManagerGeometry. Forexample: 

IconManagers 

< 

"XTerm" "=300x5+800+5" 5 
"myhost" "=400x5+100+5" 2 
} 

Clientswhose name or class isxTermwill havean entry created in thexTerm icon manager. 
C li entswhose name was myhost would be put into the myhost icon manager. 
iconManagershow{ wi n- 1 i st } T his variable specifies a list of Windows that should appear in the icon manager. When used 
in conjunction with the iconManagerDontshow variable, only the Windows i n this list will be 
shown in the icon manager. 

This variable specifies an areaon therootwindow in which iconsareplaced if no specific 
icon location is provi ded by theclient. Thegeomst r i ng isaquoted string contai ning a 
standard geometry specification. If morethan oneiconRegion line is given, iconswill be 
put into thesucceeding icon regionswhen thefirst is full . Thevgrav argument should be 
either North or south and isused to control whether icons are fi rst filled in from the 
top or bottom of theicon region. Similarly, thehgrav argument should be either East or 
west and isused to control whether iconsshould be filled in from theleft orfrom 
theright. Icons are laid outwithin the region in agrid with cellsgr d wi dt h pixelswideand 

gri dhei ght pixels high. 

T his variable specifies a list of window names and the bitmap fi lenames that should be used 
astheir icons. Forexample, 

Icons 
{ 

"XTerm" "xterm . icon " 
"xfd" "xfd_icon" 
} 



IconRegion g e o ms t r i ng 
vgra» hgrav gridwidth 
gri dhei ght 



Icons { wi n- 1 i st } 
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FI 



InterpolateMenuColors 



MakeTitle { wi n- 1 i s t } 
MaxWindowSize stri n g 

MenuBackground stri n g 

MenuFont stri n g 

Menu Foreg round stri n g 

MenuShadowColor stri n g 

MenuTitleBackground string 

MenuTitleForeground string 

Monochrome { c o I o r s } 

MoveDelta pi xel s 

NoBackingStore 

NoCaseSensitive 

NoDef aults 

NoGrabServer 



Windowsthat match "XTerm" and would not beiconified by unmappingwould try to use 
theicon bitmap in thefilexterm.icon. If Forceicons is specified, thisbitmap will beused 
even if theclient has requested itsown icon pixmap. 

This variable indicates that menu entry colors should beinterpolated between entry 
specified colors In thisexample, 

Menu "mymenu" 
< 

"Title" ("black" : "red" ) f.title 
"entryl " f . nop 
"entry2" f.nop 

"entry3" ( "white" : "green" ) f.nop 
"entry4" f.nop 

"entry5" (" red ": "white " ) f.nop 
} 

theforeground colorsfor"entryi" and "entry2" will beinterpolated between black and 
white, and the background colors between red and green. Similarly, theforeground for 
"entry4" will be halfway between white and red, and the background will behalfway 
between green and white. 

This variable specifies a list of Windows on which a une -bar should beplaced and isused 
to requesttitleson specific Windows when Nonne hasbeen set. 
Thisvariablespecifiesageometry in which thewidth and height give the maximum si ze for 
agiven window. This istypically used to restri et Windows to thesizeof thescreen. The 
default width ÌS32767— screen width. T he default height ÌS32767— screen height. 
This variable specifies the background color used for menus, and can only be specified 

inside Of a Color or Monochrome list. The default iSwhite. 

T his variable specifies the font to use when displaying menus. The default isvanabie. 
This variable specifies theforeground color used for menus and can only be specified inside 

Of a Color, Gray scale, Or Monochrome list. The default ÌS black. 

T his variable specifies the color of the shadow behind pull-down menus and can only be 

Specified inside Of a Color, Grayscale, Or Monochrome list. T he default ÌS black. 

This variable specifies the background color for f .une entri es in menus and can only be 

specified inside Of acolor, Grayscale, Or Monochrome list. The default iSwhite. 

This variable specifies theforeground color for f .une entri es in menus and can only be 

specified inside Of a color or Monochrome list. T he default ÌS black. 

This variable specifies a list of color assi gnments that should be made if the screen has a 
depth of 1. Seethe description of coiors. 

T his variable specifies the number of pixels the pointer must move before the f .move 
function starts working. Also seethef .deitastop function. The default iszero pixels 
T his variable indicates that twm's menus should not request backing store to minimize 
repaintingof menus. This istypically used with servers that can repaint faster than they can 
handle backing store. 

This variable indicates that case should beignored when sorting icon namesin an icon 
manager. This opti on istypically used with appi ications that capital izethefirst letter of 
their icon name. 

This variable indicates that twm should not supply the default ti tlebuttons and bindings. 
This option should only beused if the startup fi le contains a completely new set of bindings 
and definitions. 

Thisvariableindi cates th at t wm sh ou I d n ot grab th e server whenpoppingupmenusand 
movi ngopaque Windows. 
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NoHighlight [{ wi n- I i st }] 



NoIconManagers 
NoMenuShadows 



NoRaiseOnDeiconif y 
NoRaiseOnMove 

NoRaiseOnResize 



NoRaiseOnWarp 



NoSaveUnders 



NoStackMode [{ wi n- 1 i st }] 



NoTitle [{ wi n- I i st }] 



NoTitleFocus 



NoTitleHighlight 
[ { wi n- I i s t } ] 



OpaqueMove 



Pixmaps { pi xma ps } 



Priority p r i ori t y 



RandomPlacement 



This variable indicatesthat bordersshould not be highlighted to track the location of the 
pointer. If theoptional wi n-i i st isgiven, hi ghli ghti ng wi II only bedisabled forthose 
Windows. When the border is highlighted, itwill bedrawn inthecurrent Bordercoior. 
W hen the border is not highlighted, itwill bestippled with a gray pattern usingthecurrent 

BorderTileForeground and BorderTileBack -ground COlorS. 

Thisvariableindicatesthatno icon manager should becreated. 
This variable indicatesthat menus should not havedrop shadowsdrawn behind them. This 
istypically used with slower serversbecauseit speedsup menu drawingattheexpenseof 
making the menu slightly harderto read. 

T his variable indicatesthat wi ndows that are deiconified should not be raised. 

This variable indicatesthat Windows should not be raised when moved. This is typically 

used to allow Windows to slide underneath each other. 

This variable indicates that Windows should not be raised when resized. This is typically 
used to allow Windows to be resized underneath each other. 

Thisvariableindicates that Windows should not be raised when the pointer iswarped into 
them with thet .warpto function. If thisoption is set, warpingto an occluded window may 
result in the pointer ending up in the occludi ng window instead the desi red window, which 
causesunexpected behaviorwith t .warpring. 

This variable indicatesthat menusshould not request save-understo mi ni mize window 
repaintingfollowing menu selection. It istypically used with displaysthat can repaint faster 
than they can handlesave-unders. 

This variable indicates that client window requeststo changestacking order should be 
ignored. If theoptional wi n- 1 i st isgiven, only requestson thosewi ndows wi II beignored. 
This istypically used to prevent applicati onsfrom rei entlessly poppi ng them sei vesto the 
front of the window stack. 

Thisvariableindicates that Windows should not have ti tle-bars. If theoptional wi n- 1 i st is 
given, only thosewi ndows wi II not havetitlebars. MakeTitie may beused with thisoption 
to force titlebarsto be puton specific Windows. 

Thisvariableindicates that twin should not set keyboard input focus to each window asit is 
entered. Normally, twm sets the focus so that focus and key eventsfrom thetitlebar and icon 
managers are delivered to the application. If the pointer is moved quickly and twm isslow to 
respond, input can bedirected to the old window instead of the new. Thisoption is 
typically used to prevent this input lag and to work around bugsin older applicationsthat 
haveproblemswith focusevents. 

Thisvari ableindicates that thehighlight area of thetitlebar, which isused to indicate the 
window that currently has the input focus, should not bedisplayed. If theoptional wi n- 
i i st isgiven, only thosewindowswill nothavehighlightareas.ThisandthesqueezeTitie 
optionscan beset to substanti al ly reduce the amount of screen space required by titlebars. 
This variable indicates that thet .move function should actually move the window instead of 
just an outli ne so that the user can immedi ately seewhat the window will look likein the 
new position. Thisoption istypically used on fast displays {parti cularly if NoGrabserver is 
set). 

T his variable specifies a list of pixmaps that define the appearanceof variousimages. Each 
entry isa keyword indicating thepixmap to set, followed by a string giving thenameof the 
bitmap file. Thefollowing pixmaps may bespecified: 0 pixmaps { TitieHigniignt 

"grayl" } 

The default fonitieHighiight isto usean even stipple pattern. 
Thisvariablesetstwm's priority. priority should bean unquoted, signed number(for 
example, 999). This variable has an effect only if the server supportstheSYN C extension. 
This variable indicates that Windows with no specified geometry should be placed in a 
pseudorandom location instead ofhaving the user drag out an outline. 
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ResizeFont string 
RestartPreviousState 

SaveColor { c o I or s ■ I i s t } 



ShowIconManager 

SortlconManager 

SqueezeTitle 

[ { s q ueeze- I i s t }] 



Startlconif ied 
[{ wi n- I i st }] 



TitleBackground string 

[{ wi n- I i st }] 

TitleButtonBorderWidth 

pi x e I s 



This variable specifies the font to beused for in thedimensionswindow when resizing 
Windows. The default istixed. 

This vari ableindicatesthat twm should atterri pt to use the wm_state property on client 
Windows to teli which Windows should beiconified and which should beleft visi ble This is 
typically used to try to regenerate the state that the screen wasin before the previ ous 
window manager wasshutdown. 

This variable indi cates a list of color assi gnmentsto bestored as pixel valuesin theroot 
window property _mit_priority_colors. C lients may elect to preserve thesevalues when 
installi ng thei r own colormaps. Note that use of thismechanism isawayforan application 
to avoid the "technicolor" problem, whereby useful screen objectssuch as window borders 
and titlebarsdisappear when a program'scustom colors are installed by thewindow 
manager. For example 

SaveColor 
{ 

BorderColor 

TitleBackground 

TitleForeground 

"red" 

"green" 

"blue" 

} 

Thiswould placeon the rootwindow three pixel valuesfor borders and titlebars, aswell as 

thethree color strings, ali taken from the default colormap. 

This variable indi cates that thei con manager window should bedisplayed when twmis 

started. It can always bebrought up using thet .showiconmgr function. 

Thisvariable indicatesthat entries in theicon manager should besorted alphabetically 

rather than by si mply appendi ng new wi ndows to the end. 

Thisvariable indicates that twm should attemptto usethesHAPE extension to maketitlebars 
occupy only asmuch screen space asthey need, rather than extending ali theway acrossthe 
top of thewindow. The optional squeeze- 1 i st may beused to control the location of the 
squeezed titlebar along the top of thewindow. It contai ns entries of the form: 0 ■ name" 
justification nu m d e n o m where n a me isa window name, j usti fi cati on is either left, 
center, or right, and n u m and d e no m are numbers specifying a ratio givi ng the relative 
position about which the titlebar isjustifi ed. The ratio ismeasured from left to right if the 
numerator is positive, and right to left if negative. A denominator of 0 indicatesthat the 
numerator should bemeasured in pixel s. For conveni enee, the ratio 0/0 isthesameasi/2 
for center and -1/1 for right. Forexample, 

SqueezeTitle { "XTerm" left 0 0 "xterml" left 1 3 "xterm2" left 2 3 
"oclock" center 0 0 "emacs" right 0 0} 

TheDontsqueezeTitie list can beused to turn off squeezingon certain titles. 
Thisvariable indicatesthat client Windows should irriti ally beleft asicons unti I explicitly 
deiconified by the user. If theoptional wi n- 1 i st isgiven, only thosewi ndows wi II be 
started iconic. This is useful forprogramsthatdo notsupportan -iconic command-line 
option or resource. 

This variable specifies the background color used in titlebars, and may only be specifico 1 
inside of a color, Grayscaie, orMonochrome list. T he optional wi n- li st is a list of window 
namesand colors so that per-window colors may be specifi ed. The default iswnite. 
This variable specifies the width in pixelsof theborder surrounding titlebuttons This is 
typically set to 0 to allow titlebuttons to takeup asmuch space as possibleand to not havea 
border. The default isi. 



552 



Parti: U ser Commands 



TitleFont stri ng 

TitleForeground stri n g 
[{ wi n- I i st }] 

TitlePadding pi xel s 

Unknownlcon stri n g 

UsePPosition stri ng 



T h i s vari abl e specifies the font to beused for displaying window namesin titlebars. The 

default ÌSvariable. 

This variable specifies the foreground color used in titlebars, and may only bespecified 
inside of a color, Grayscaie, orMonochrome list. The optional wi n- li st is a list of window 
namesand colorsso that per-window colorsmay be specifi ed. The default isbiack. 
T his variable specifies the distance between the vari ous buttons, text, and highlight areasin 
thetitlebar. The default is s pixels. 

T his variable specifies the fi lenameof a bitmap file to beused as the default icon. This 
bitmap wi 1 1 beused as the icon of ali clientsthat do not provide an icon bitmap and arenot 
listed in the icons list. 

This variable specifies whether or nottwm should honor program-requested locations (given 
by thepposition flag in thewM_NORMAi__HiNTs property) in theabsenceof auser-specified 
position. T he argument stri ng may haveoneof threevalues: off (the default), indicating 
that twm should ignoretheprogram-supplied position; on, indicating that the position 
should beused; and non -zero, indicating that the position should used if it isother than 
(0,0). Thelatter option isfor working around a bug in older toolkits. 
Thisvariableindicatesthatthepointer should bewarped into windowswhen they are 
deiconified. If the optional wi n- 1 i st is given, the pointer wi II only bewarped when those 
Windows are deiconified. 

This variable specifies a list of Windows along which thef .warpring function cycles. 
T his vari ableindicates that the f.warpto function should deiconify any iconified Windows 
it encounters. This is typically used to makea key binding that wi II pop up a parti cular 
window (such asxmh) no matterwhereit is. The default isfor f.warpto to ignore iconified 
Windows. 

This variable specifies the valueto use when drawing window outlinesfor moving and 
resizing. This should be setto a valuethat will result in a variety of disti nguishable colors 
when exclusiveoR isused with the contents of the user's typical screen. Setti ng this variable 
to 1 often gi ves nice results if adjacent colors in the default colormap are distinct. By 
default, twm will atterri pt to cause temporary linesto appear attheoppositeend of the 
colormap from the graphics 

This vari ableindicates that outlinessuggesting movement of a window to and from its 
iconified state should bedisplayed whenever a window is iconified or deiconified. The 
optional count argument specifies the number of outlinesto bedrawn. The default count 

ÌS 8. 

T he following vari ables must beset after the fontshavebeen assigned, so it isusually best to put them at the end of the 
vari abl es or at the beginning of the bindings sections 

DefauitFunction function T his variable specifies the function to beexecuted when a key or button event isreceived for 
which no binding isprovided. This is typically bound to f .nop, f .beep, or a menu 
containing window operations. 

windowFunction function T his variable specifies the function to executewhen awindow is selected from the 

Twmwindows menu. If this variable is not set, thewindow will be deiconified and raised. 



WarpCursor [{ wi n- I i st }] 



WindowRing { wi n ■ I i s t } 
WarpUnmapped 



XorValue number 



Zoom [ count 



BINDINGS 

After the desi red vari ables have been set, functionsmay beattached ti ti ebutto ns and key and pointer buttons. Ti ti ebutto ns 
may beadded from the left or right side and appear in thetitlebar from left to right accordi ngto the order in which they are 
specifi ed. Key and pointer button bindings may be given in any order. 

Titlebuttons' specifications must include the nameof the pixmap to use in the button box and the function to beinvoked 
when a pointer button is pressed within them: 
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0 LeftTitleButton " b i t ma p n a me " =f j r c t i o n 

or 

0 RightTitleButton "bi t mapname "=f unct i on 

Thebi t mapname may refer to oneof thebuilt-in bitmaps(which arescaled to match ntie-Font) by usi ng the appropriate 
colon-prefixed namedescribed earlier. 

Keyand poi nter button specifications must givethe modifi ers that must bepressed, overwhich partsof thescreen the 
pointer must be, and what function isto beinvoked. Keysaregiven as stri ngscontaining the appropri atekeysym name; 

buttonsaregiven asthekeywordSButtonl -Button5: 0 "FP1" = modi i st : context : function Buttonl = modlist : 
cont ext : function 

The modi i st isany combination of the modifi er namesshift, control, look, meta, modi, mod2, mod3, mod4, ormods (which 
may beabbreviated ass, c, 1, m, mi, m2, m3, m4, m5, respectively) separated by averti cai bar (|). Similarly, thecont ext isany 
combination of window, titie, icon, root, trame, iconmgr, theirfirst letters (iconmgr abbreviation ism), orali, separated 
by a vertical bar. The function isany of the f keywordsdescribed in thefollowing list. For example, the default startup fi le 
contai ns the following bindings: 



Buttonl 






root : f. 


menu "TwmWindows" 




Buttonl 




m 


: window 


] icon : f. function "move-or 


lower 


Button2 




m 


: window 


| icon : f.iconify 




Button3 




m 


: window 


] icon : f. function "move-or 


raise 


Buttonl 






title : f 


.function "move -or- raise " 




Button2 






title : f 


. raiselower 




Buttonl 






icon : f. 


function "move-or-iconify" 




Button2 






icon : f. 


iconif y 




Buttonl 






iconmgr : 


f . iconif y 




Button2 






iconmgr : 


f . iconify 





A userwho wanted to beableto manipulate Windows from thekeyboard could use thefollowing bindings: 

"F1" = : ali : f.iconify 
"F2" = : ali : f. raiselower 
"F3" = : ali : f.warpring "next" 
"F4" = : ali : f.warpto "xmh" 
"F5" = : ali : f.warpto "emacs" 
"F6" = : ali : f.colormap "next" 
"F7" = : ali : f.colormap "default" 
"F20" = : ali : f .warptoscreen "next" 
"Left" = m : ali : f . backiconmgr 
"Flight" = m | s : ali : f .f orwiconmgr 
"Up" = m : ali : f.upiconmgr 
"Down" = m | s : ali : f . downiconmgr 

twm providesmany more window manipulation primi ti vesthan can be conveniente stored in atitlebar, menu, orsetof key 
bindings. Although asmall set of defaults issupplied (unlesstheNoDefauits isspecified), most userswill want to havetheir 
most common operationsbound to key and button strokes. To do this, twm associates nameswith each of theprimitivesand 
providesuser-defined functionsfor building higher level primitivesand menusfor interactively selectingamonggroupsof 
functions 
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User-defined functions contai n the nameby which they are referenced in Calisto f .function and a list of otherfunctionsto 
execute. For example, 

Function "move-or-lower" { f .move f.deltastop f .lower } 

Function "move-or-raise" { f.move f.deltastop f.raise } 

Function "move-or-iconify" { f.move f.deltastop f.iconify } 

Function " restore-colormap" { f.colormap "default" f. lower } 

The function namemust beused in f .function exactly asit appears in the function specificati on. 

In the followi ng descri ptions, if thefunction i s sai d to operate on the selected window, butisinvoked from arootmenu, the 
cursorwill bechanged to theSelect cursorand the next window to receivea button press wi II bechosen: 



! stri n g 
f . autoraise 

f . backiconmgr 



beep 

bottomzoom 

circledown 
circleup 
colormap stri n g 



f . deiconif y 



f .delete 



f.deltastop 



f .destroy 



f . downiconmgr 



f . exec stri n g 



f .focus 



Thisisan abbreviation for f .exec string. 

This function toggleswhether or not the selected window is raised whenever entered by the 
pointer. See the descri ption of thevariableAutoRaise. 

This function warps the pointer to thepreviouscolumn in thecurrent icon manager, 
wrappi ng back to the previ ous row if necessary. 
This function soundsthekeyboard beli. 

This function issimilarto thet .fuiizoom function, but resizes the window to fili only the 
bottom half of thescreen. 

This function lowers the topmost window that occludesanother window. 

This function raisesthe bottom most window that isoccluded by another window. 

T his function rotatesthecolormaps(obtained from thewM_coi_oRMAP_wiNDows property on 

the window) that twm will display when the pointer isin this window. The argument 

string may haveoneof the followi ngvalues: next, prev, and defauit. It should benoted 

here that in general, theinstalled colormap isdetermined by keyboard focus. A pointer- 

driven keyboard focus will instali a private colormap upon entry ofthewindow owningthe 

colormap. Usingtheclick-to-type model, private colormaps will not beinstalled until the 

user clicks on the target window. 

This function dei conifies the selected window. If the window isnot an icon, this function 
does nothing. 

T his function sends the wm_delete_window messageto the selected window if the eli ent 
application hasrequested itthrough thewMj>ROTocoi_s window property. The application is 
supposed to respond to themessageby removi ng the indicated window. If the window has 
not requested wm_delete_window messages, the keyboard beli will berung, indicating that 
the user should choosean alternative meth od. N otethisis very different from f. destroy. 
The intent here i sto delete a single window, not necessari ly the enti re application. 
Thisfunction allowsa user-defined function to beaborted if the poi nter hasbeen moved 
morethan MoveDeita pixels. Seetheexampledefinition given for Function "move-or- 
raise " at the beginning of the section. 

Thisfunction i nstruets the x server to dose the display connection of the client that created 
the selected window. This should only beused asa last resortfor shutting down runaway 
clients. See also f .deiete. 

Thisfunction warps the pointer to the next row in thecurrent icon manger, wrapping to 
the beginning of the next column if necessary. 

Thisfunction passes the argument string to /bin/sn forexecution. In multiscreen mode, 
if st ri ng startsa new x client withoutgiving a display argument, the client will appearon 
thescreen from which thisfunction wasinvoked. 

T his function toggles the keyboard focus of the server to the selected wi ndow, changi ng the 
focus mie from pointer-driven if necessary. If the selected window already wasfocused, this 
function executes an f . unf ocus. 
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Thisfunction isliket .move exceptthat it ignorestheDontMoveotf variable. 
Thisfunction warps the pointer to thenextcolumn in thecurrent icon manager, wrapping 
to thebeginningof thenext row if necessary. 

Thisfunction resizestheselected window to the full sizeof the display or else resto res the 
ori gi nal size if the wi ndow was al ready zoomed. 

Thisfunction executestheuser-defined function whosenameisspecified by theargument 

stri n g . 

Thisfunction isasynonym for f . bottomzoom. 
Thisfunction unmaps thecurrent icon manager. 

This variable issi mi larto the f. zoom function exceptthat the sei ected window isresized to 
the full width of the display. 
Thisfunction isasynonym fort .topzoom. 
Thisfunction isasynonym fort .horizoom. 

Thisfunction iconifiesordeiconifiestheselected window or icon, respectively. 
Thisfunction displaysasummary of thenameand geometry of theselected window. If the 
server su ppo rts th e sync exten si o n , the priority of the client owning the window is also 
displayed. Clicking the pointer or pressing a key in the window will dismiss it. 
T his function is simi lar to f . backiconmgr except that wrappi ng does not change rows. 
This variable issi mi larto the f. bottomzoom function but causes theselected window to be 
resized only on theleft half of the display. 
Thisfunction lowers the sei ected window. 

Thisfunction invokes the menu specified by theargument stri ng. Cascaded menusmay be 
built by nesting Calisto t. menu. 

Thisfunction dragsan outlineof theselected window (or the window itself if the 
opaqueMove variable is set) until theinvoking pointer button is released. Double-clicking 
within the number of millisecondsgiven by constrainedMoveTime warps the pointer to the 
center of the window and constrains the movete beeither horizontal or veti cai, dependi ng 
on which grid lineiscrossed. To abort a move, press another button before releasing the 
first button. 

Thisfunction warps the pointer to thenext icon manager contai ni ngany Windows on the 
current or any succeeding screen. 

Thisfunction does nothing and istypically used with the Defauit- Function or 
windowFunction vari ables orto introduce blank linesin menus. 
Thisfunction warps the pointer to the previous icon manager contai ni ngany Windows on 
thecurrent or precedi ng screens. 

Thisfunction sets the priority of the client owning the sei ected window to thenumeric 
valueof theargument st ri ng, which should bea signed integer in doublé quotes (for 
example, "999"). Thisfunction has an effect only if the server supports the sync extension. 
Thisfunction causes twm to restare the window'sborders and exit. If twm isthefirst client 
invoked from xdm, this will result in a server reset. 
Thisfunction raises the sei ected window. 

Thisfunction raises the sei ected window to the top of thestacking order if it isoccluded by 
any Windows; otherwise, thewindow islowered. 
Thisfunction causes ali Windows to berefreshed. 

Thisfunction displaysan outlineof theselected window. Crossing a border (or setti ng 
AutoReiativeResize) will causetheoutlineto begin to rubber band until theinvoking 
button isreleased. To abort a resize, press another button before releasing the first button. 
Thisfunction killsand restartstwm. 

Thisfunction is simi lar to f.nexticonmgr except that wrappi ng does not change rows. 
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f . rightzoom 
f . saveyourself 



f . showiconmgr 
f . sorticonmgr 

f .title 

f .topzoom 

f . unf ocus 

f . upiconmgr 

f . vlzoom 
f . vrzoom 

f .warpring stri n g 
f .warpto stri n g 

f .warptoiconmgr string 

f .warptoscreen string 



f .winref resh 



f . zoom 



This vari able issi mi lar to thet .bottomzoomfunction except that the selected window is 
only resized to the right half of the display. 

Thisfunction sends a wm_saveyourself messageto the selected window if it has requested 
themessagein itswM_PROTocoi_s window property. Clients that acceptthismessage are 
supposed to checkpoint ali states associ ated with thewindow and update thewM_coMMAND 
property asspecified in the icccm. If the selected window hasnot been selected for this 
message, thekeyboard beli will berung. 
Thisfunction mapsthecurrent icon manager. 

Thisfunction sorts the entri es in thecurrent icon manager alphabetically. See the vari able 

SortlconManager. 

Thisfunction providesacentered, unselectableitem in amenu definition. Itshould not be 
used in any otner context. 

This vari able issi mi lar to thet .bottomzoomfunction except that the selected window is 
only resized to the top half of the display. 

Thisfunction resets the focus back to pointer-driven. Thisshould beused when afocused 
window isno longer desired. 

Thisfunction warps the pointer to theprevious row in thecurrent icon manager, wrapping 
to thelast row in thesamecolumn if necessary. 
Thisfunction isasynonym forf .ìeftzoom. 
Thisfunction isasynonym fort .nghtzoom. 

Thisfunction warps the pointer to thenext or previ ous window (asindicated by the 
argument st r i ng, which may be "next" or "prev") specified in thewmdowRing variable. 
Thisfunction warps the pointer to thewindow that has a nameor class that matches 
string. If thewindow isiconified, itwill bedeiconified if thevariablewarpunmapped is set 
orelseignored. 

This function warps the pointer to the icon manager entry associated with thewindow 
contai ni ng the pointer in the icon manager specified by the argument st r i ng. If st r i ng is 
empty (that is, 11 ■), thecurrent icon manager ischosen. 

Thisfunction warps the pointer to thescreen specified by the argument st ri ng. st ri ng 
may bea number (such as'V or "1"), the word ■ next" (indicating thecurrent screen plus 
1, skippi ng over any unmanaged screens), the word "back" (indicating thecurrent screen 
minusl, skippi ng over any unmanaged screens), or the word " prev" (indicating thelast 
screen visited. 

Thisfunction issimi lar to thet .ret resh function except that only the selected window is 
refreshed. 

Thisfunction issimi lar to thet .fuiizoom function, except that only the height of the 
selected window ischanged. 



MENUS 



Functionsmay begrouped and interactively selected using pop-up (when bound to a pointer button) or pull-down (when 
associated with atitlebutton) menus. Each menu specification contains the nameof the menu as itwill bereferred to by 
f .menu, optional default foreground and background colors, the list of item namesand thefunctionsthey should invoke, 
and optional foreground and background colors for individuai items: 

Menu "me n u n a me " [ ( "d e f f o r e " : "d ef b a c k " ) ] { stringi [ ( "f o r e 1 " : "b a c k n " ) ] functi onl stri n g 2 
[ ( "f o r e 2 " : "b a c k n " ) ] function2 ...stri ri g N [ ( "f o r e N " : "b a c k N " ) ] functionN } 

Themenuname iscase-sensi tive. T he optional deffore and detback argumentsspecify the foreground and background colors 
used on acolor display to highlight menu entries. The string portion of each menu entry will be the text that will appear in 
the menu. The optional tore and back argumentsspecify the foreground and background colors of the menu entry when the 



twm 




pointer is not in the entry. Thesecolorswi II only beused on a color display. The default isto usethe colors specified by the 
MenuFor-eground and MenuBackground variables. T he f unction porti on of the menu entry isoneof thefunctions, includi ng 
any user-defined functions, or additional menus. 

There isa special menu named Twmwindows that containsthe namesof ali of the eli ent and twm-supplied Windows. Selecting 
an entry wi II cause the windowFunction to beexecuted on that window. If windowFunction hasn't been set, thewindow will 
bedeiconified and raised. 

ICONS 

twm supports several different ways of manipulating iconified Windows. The common pixmap-and-text style may be laid out 
by hand or automatically arranged asdescribed by theiconRegion variable. In addi ti on, atersegrid of icon names, called an 
icon manager, providesa more efficient useof screen space aswell astheability to navigate among Windows from the 
keyboard. 

An icon manager isa window that contai ns namesof selected Windows or ali Windows currently on the display. In addition 
to thewindow name a small button using the default iconify symbol will bedisplayed to theleft of thenamewhen the 
window is iconified. By default, clicking on an entry in the icon manager performsf .iconify. To changetheactionstaken 
in the icon manager, usetheiconmgr context when specifying button and keyboard bindings. 

If you move the pointer into theicon manager, the keyboard focusisalso directed to theindicated window (setti ng the focus 

explicitly Or else sending SynthetiC eventSNoTitleFocus ÌS set). U Sing thef .upiconmgr, f .downiconmgr, f .lefticonmgr, 

and f. right iconmgr functions, the input focus can bechanged between Windows di rectly from the keyboard. 
BUGS 

The resource manager should havebeen used instead of ali of thewindow lists. 
The iconRegion variable should take a list. 

D ouble-clicking very fast to gettheconstrained movefunction will sometimes cause the window to move, even though the 
pointer is not moved. 

If IconifyByUnmapping ison and Windows are I i Sted in IconManagerDontShow but not in Dontlconif yByUnmapping, they 

may belost if they are iconified and no bindingsto t .menu "Twmwindows" ort .warpto aresetup. 
FILES 

$HOME/ . twmrc. <screen number> 
$HOME/.twmrc 

<XRoot>/lib/X1 1 /twm/system. twmrc 

EN VIRO NMENT VARIABLES 

display This variable is used to determi ne which x server to use 1 1 i s al so set duringt .exec so that programscomeup on 
theproper screen. 

home Thisvariableisused as the prefix for files that begin with a tilde and for locati ng the twm startup fi le. 
SEEALSO 

x(l), Xsenver(l), xdm(l), xrdb(l) 

AUTHORS 

Tom LaStrange, Solbourne Computer; Jim Fulton, M IT X Consortium; Steve Pitschke, Stardent Computer; Keith Packard, 
M IT X Consortium; DavePayne, Apple Computer. 

SEEALSO 

X(l), Xserver(l), x 

X Versi on 11 Re!ease6 
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txt2gcal 

txt2gcai— Createsaverbatim gcai resourcefilefrom atextfile 
SYNOPSIS 

txt2gcal [ --help ] --version ] ] [ T e x t - f i I e ] - ] [Date- part ] 

D ESC RIFIO N 

txt2gcai is a program that createsaverbatim gcai resourcefilefrom atext file. If no t ext ■ f il e or - argument isgiven, the 
program readsand processesall input received from the standard input channel. If no date - part argument isgiven, 
txt2gcai createsa a for the date part. Ali resultsarealwaysshown on the standard output channel. An exit status of 0 means 
ali processing issuccessfully done; any othervalue means an errar hasoccurred. 

OPTIONS 

--heip Print a usage message listing ali available options, then exitsuccessfully. 

--version Print the version number, then exitsuccessfully. 

COPYRIGHT 

Copyright© 1996 Thomas E sken. This software doesn't claim completeness, correctness, or usabili ty. On principle, I wi 1 1 not 
beliablefor any damagesor losses (implicitor explicit), which resultfrom usingor handling my software. If you use this 
software, you agreewithout anyexception to this agreement, which bindsyou legai ly. 

txt2cai isfree software and distri buted under thetermsof theGNU General Public License; published by the F ree Software 
Foundation; version 2 or (atyour option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposalsforcontractwork, and so forth are welcome. If 
you likethistool, l'd appreciatea postcard from you! 

Enjoy it =8") 
AUTHOR 

Thomas Esken (esken@uni-muenster-.de) 

m H agenfeld 84 

D -48147 M uenster; Germany 

Phone: +49 251 232585 

SEEALSO 

gcal(l), tcal(l) 

16 July 1996 

ul 

ul— Do underlining 
SYNOPSIS 

ul [ -i] [ -t terminal] [name . . . ] 

D ESC RIFIO N 

ui readsthenamed fi les (or standard input if none aregi ven) and translatesoccurrencesof underscoresto the sequence that 
indicete underlining for the terminal in use, as specified by the environment vari ableTERM . The fi le /etc/termcap isread to 
determi ne the appropriate sequences for underlining. If the terminal isincapableof underlining but iscapableof astandout 
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mode, then that isused instead. If the terminal can overstri ke, or handlesunderl ini ng automati cally, ui degeneratesto 
cat(l). If theterminal cannot underline, underlining isignored. 

T he followi ng opti ons are available: 

-i U nderli ni ng isindicated by a separate li ne contai ni ng appropriate dashes -; this is useful when you want to 

look at the underlining which ispresent in an nroff output stream on a CRT terminal, 
-t terminai 0 verri des the terminal typespecified in theenvironmentwith terminal. 

ENVIRONMENT 

The followi ng environment vari able isused 

term Relatesa tty devicewith its device capabi li tydescription; see termcap(5). terni isset at login ti me, either 

by the default terminal typespecified in /etc/ttys or as set during the login processby the user in the 
login file; seesetenv(l). 

SEEALSO 

man(l), nroff(l), colcrt(l) 

BUGS 

nroff usually outputsa seriesof backspaces and underlines intermixed with thetext to indicate underlining. N o attempt is 
madeto opti mize the backward motion. 

HI STORY 

Theui command appeared in BSD 3.0. 

BSD 4, 6junel993 

unexpand 

unexpand— Convert spacesto tabs 
SYNOPSIS 

unexpand [ -t a b 1 [ ,t a b2 [,...]] ] [ -t t abl [ ,t a b 2 [,...]] ] [ -a] [- -tabs=t abl [ ,t ab2 [,...]] ] 
[--ali] [--help] [--version] [file...] 

D ESC RIFIO N 

Thismanual page documents the GN U version of unexpand. unexpand writesthecontentsof each given file, or the standard 
input if none are given or when afilenamed - is given, to the standard output, with stringsof two or more space or tab 
characters converted to asmany tabs aspossi blefollowed byasmanyspacesasareneeded. By default, unexpand converts 
only initial spaces and tabs (those that precede ali characters that aren't spaces or tabs) on each line. Itpreserves backspace 
characters in the output; they decrement thecolumn countfortab calculations. By default, tabs are set at every 8th column. 

0PTI0NS 

-, -t, - -tabs t abi [ ,t a b 2 [,...] ] If only one tab stop isgiven, set the tabst a b 1 spaces apart i nstead of the default 8. 

Otherwise, set the tabs atcolumnst abi, t a b 2 , and so on (numbered from 0) and 
leave spaces and tabsbeyond the tab stops given unchanged. If the tab stopsare 
specified with the -t or - -tabs option, they can beseparated by blanksaswell as by 
commas. Thisoption impliesthe -a option. 

-a, - -ali Convert ali stringsof two or more spaces or tabs, not just initial ones, to tabs. 

- -heip Print ausagemessageand exit with a non-zero status. 

--version Print version information on standard output, then exit. 



GNU TextUtilities 
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uniq 

uniq— Remove duplicate linesfrom asorted file 
SYNOPSIS 

uniq [-cdu] [-f skìp-fields] [-s skip-chars] [-w check-chars] [ -#skip-f ields] 
[+#skip-chars] [--oount] [--repeated] [--unique] [ - -skip-fields=skip-fields] 
[ - -skip-chars=skip-chars] [ - -check-chars=check-chars] [--help] [--version] 
[infile] [outfile] 

D ESC RIFIO N 

Thismanual page documents the GN U version of uniq. uniq printstheuniquelinesin asorted file, di scardi ng al I butoneof 
arun of matching lines.lt can optional ly show only linesthat appear exactly once, or linesthat appear morethan once, uniq 
requires sorteci input becauseitcompares only consecutive lines. 

If the output file isnot specified, uniq writesto the standard output. If the input file isnotspecifi ed, it readsfrom the 
standard input. 

OPTIONS 

-u, - -unique 
-d, - - repeated 
-c, - -count 
-n u mb e r , -f , 
- - skip-f ields=n u mb e r 



+n u mb e r , - s, 

- -skip-chars=number 

-w, 

- - check - chars=number 

- - help 

- - version 

GNU TextUtilities 



Only print unique lines 
Only print duplicate lines 

Print thenumber of timeseach lineoccurred along with the line 
In thisoption, number isan integer representi ng thenumber off ields to skip over 
beforecheckingfor uniqueness. Thefirst number fields, along with any blanks 
found beforenumber fields isreached, areskipped over and notcounted. Fields are 
defined as a stri ngs of nonspace, nontab charactersthatareseparated from each 
other by spaces and tabs. 

In thisoption, number isan integer representi ng the number of charactersto skip 
over beforecheckingfor uniqueness. Thefirst number characters, along with any 
blanks found beforenumber characters isreached, areskipped over and notcounted. 
If you use both the fi eld and character skipping options, fields areskipped over first. 
Specify thenumber of charactersto compare in the lines, after skipping any specified fields 
and characters. N ormally, the enti re remainder of the lines are compared. 
Print a usage message and exit with a non-zero status. 
Print version information on standard output, then exit. 



unshar 

unshar— Unpackasharfile 

SYNOPSIS 

unshar [ -d directory ] [ -c ][-e j -E exit_line ] [file ... ] 

D ESC RIFIO N 

unshar scans mail messageslookingfor the start of ashell archive. 1 1 then passesthearchivethrough a copy of the shell 
to unpack it. It will accept multi pie fi les. If no filesaregiven, standard input isused. Thismanual page refi ects unshar 
version 4.0. 



updatedb 



OPTIONS 

Optionshaveaone-letter version starti ng with - or a long versi on starti ngwith - - . Theexceptionsare - -heip and 
version, which don't have a short version. 



FI 



- - version 
- -help 

-d DI RECTORY 

- -directory=D RECTORY 

-c --overwrite 



-e --exit-0 



-E STRI NG 

- -split -at=5T RI NG 



P ri nt the version numberof the program on standard output, then immedi ately exit. 
Print a help summary on standard output, then immediately exit. 

Change directory tO DI RECTORY 

beforeunpackingany files. 

Passed asan option to the shar file. M any shell archive seri pts {i ncludi ng those produced by 
shar 3.40 and newer) accepta -c argumentto indicate that existing fi les should be 
overwritten. 

This option exists mainly for peoplewho collect many shell archi ves into a single mail 
folder. With thisoption, unshar isolateseach different shell archive from theothersthat 
havebeen put in thesamefile, unpacking each in turn, from thebeginningof the fi le 
towardsitsend. Itsproper operati on relieson the fact that many shar fi les are termi nated 
byanexit aat thebeginningof aline. 
Option -e isinternally equivalentto -e "exit 0". 

Thisoption works like - e, but it allowsyou to speci fy the stri ng that separates archi ves 
if exit 0 isn't appropriate. Forexample, noticing that most .signatures havea -- 
on a lineright beforethem, onecan sometimesuse - - split -at=- - for splitting shell 
archi ves that lack the exit 0 lineat end. The signature wi II then beskipped altogether with 
theheaders of thefollowing message. 

SEEALSO 

shar(l) 

DIAGNOSTICS 

Any message from the shell may bedisplayed. 

AUTHORS 

M ichael M auldin at Carnegie-M ellon U niversity, Guido van Rossum at CWI, Amsterdam (guido@mcvax), Bill Davidsen 

(davidsen@sixhub.uuxp), Warren Tucker (wht%n4hgf@gatech.edu) 

Richard H . Gumpertz (rhg@cps.coM), and ColasNahaboo (coias@avahi.inria.fr). M an pagesbyjan Djfrv 
(j hd@irfu.se). 

12 August 1990 



updatedb 

updatedb— U pdate a filename database 
SYNOPSIS 

updatedb [opt i ons J 

DESCRIPTION 

Thismanual page documents the GN U version of updatedb, which updatesfilenamedatabasesused by GN U locate. The 
fi lename databases contai n I ists of fi les that were i n particular di recto ry trees when the databases were last updated. The 
fi lenameof the default database isdetermined when locate and updatedb are confi gured and installed. The frequency with 
which the databases and the directories for which they contai n entri es are updated dependson how often updatedb isrun, 
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and with which arguments. In networked environments, it often makessenseto build a database at the rootofeach 
filesystem, contai ni ng the entriesforthat fi lesystem. To prevent thrashing the network, updatedb isthen run for each 
filesystem on thefileserverwherethat filesystem ison alocal disk. Userscan select which databases locate searches usi ngan 
environment variableor command-lineoption; seeiocate(lL). Databases can not beconcatenated together. Thefilename 
database format changed starti ng with GNU find and locate version 4.0 to allow machineswith different byteorderingsto 
share the databases. The new GNU locate can read both the old and new database formats. H owever, old versionsof 
locate and find produce i ncorrect resultsif given a new-format database. 

0PTI0NS 

- -localpaths='pat hi p a t h 2 . . 

- -netpaths= ' p a t hi pat h 2 . . . 1 

- -prunepaths='pat hi p a t h 2 . . 

- -output=dbf i I e 

- -netuser=us er 
- -old-format 

- - version 
- -help 

SEEALSO 

find(lL), ìocate(lL), iocatedb(5L), xargs(lL) FindingFiles(onlinein info, or printed) 

uptime 

uptime— Teli how longthesystem hasbeen running 
SYNOPSIS 

uptime 

DESCRIPTION 

uptime givesa one-line display of the information thatfollowsit: thecurrenttime how longthesystem hasbeen running, 
how many usersarecurrently logged on, and the system load averagesfor thepast 1, 5, and 15 minutes. 

Thisisthesameinformation contained in the header linedisplayed by w(l). 
FILES 

/var/run/utmp Information aboutwho iscurrently logged on 
/proc Process information 

AUTHORS 

uptime waswritten by Larry G reenfi eld (greenfie@gauss.rutgers.edu) and M ichael K. Johnson 

(johnsonm@sunsite. une. edu). 

SEEALSO 

ps(l), top(l), utmp(5), w(l) 

C ohesi ve Systems 26 January 1993 



N onnetwork di rectories to put in the database. D efault is/. 

N etwork (nfs, afs, rfs, and so on) directoriesto put in thedatabase. Default is 

none. 

D i rectories to not put in thedatabase, which would otherwisebeput there. Default 

is/tmp /usr/tmp /var/tmp /afs. 

The database file to build. Default issystem-dependent, but typically /usr/iocai/ 

var/locatedb. 

The user to search network di rectories as, using sufi). Default isdaemon. 
Create the database in the old format instead of the new one. 
P ri nt the version number of updatedb and exit. 
Printasummary of theoptionsto updatedb and exit. 



uucp 




userlist 

user-list— User listi ng of who's on your system 
SYNOPSIS 

userlist 

D ESC RIPTIO N 

This program simply givesyou a listing of who isconnected to your system. It isused primarily in thesorted listi ngthat 
uti litizes the samemethod of display fora more uniform output Petween systems. Italso mademoresenseto do itthisway 
instead of havingjumPIed up display listingsin sorted finger displays. Besides, it mademoresenseto do thisthan use 

finger. :) 

This program functionswith thesametypesof thingsin mind that cfingerd does. If the user hasa .nofinger file, hisor her 
usernamewill not Pedisplayed in theuser listing. 

Exampleoutput isshown as 

Username Real Name Idletime TTY Remote console username I'm real . . . 9d 23:59 0 
(remote. site. com) 

where it would display the user'slogin name, theuser's real name, theuser's idle time given in the format "dd hh: mm", the 
tty, and the remote location (or where the user istelnettingfrom). 

If the username is more than a certain numPer of characters, the program will not search fortheir information in thepasswd 
filePecauseitmayPetoo long. Besides, itchecksgetpwnam, anyway. 

CONTACTING 

If you li ke this program, haveany suggestionson how it could Pemodified, or havePug reports, pleasewriteto 

khollis@bitgate.com. 

Yourcontinued puPlic domain support is appreciated! T hanks. 
SEEALSO 

cfingerd .conf(5), cfingerd(8), finger(l) 

Userlist 0.0.1, 26 August 1995 

uucp 

uucp- UNIX-to-U NIX copy 

SYNOPSIS 

uucp [ options ] s o u r c e - f i ! e destination-file 

uucp [ options ] source-fi I e. . . desti nati on-di rectory 

D ESC RIFIO N 

The uucp command copies fi les Petween systems. Each file argument iseither a pathnameon the locai machine or isof the 
form 

system! pat h 

which isinterpreted as Peingon a remote system. In the first form, the contents of thefi rst fi le are copied to thesecond. In 
the second form, each source fileis copied into thedestination directory. 
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A file betransferred to orfrom syst em2 viasyst e mi by using 

systeml !system2 !path 

Any pathnamethat doesnot begin with / or " will beappended to thecurrent directory (unlessthe -wor - -noexpand option 
isused); this resulti ng path will not necessari ly exist on a remote system. A pattinarne beginning with a si m pie - startsat the 
uucp public directory; a pathnamebeginningwith ~name startsat the home directory of thenamed user. The ~ isinterpreted 
on the appropriate system. N otethat some shells will interpret a simple ~ to the locai home directory beforeuucp seesit; to 
avoid this, the " must be quoted. 

Shell metacharacters ? * [ ] are i nterpreted on the appropriate system, assumingthey arequoted to preventtheshell from 
interpretingthem first. 

Thecopy doesnottakeplaceimmediately, butisqueued upfortheuucico(8) daemon; thedaemon isstarted immediately 
unlessthe -r or - - nouucico switch isgiven. In any case, the next ti me the remote system iscalled, the f i le(s) will becopied. 

OPTIONS 

T he followi ng opti ons may be gi ven to uucp. 

Do not copy locai source fi lesto the spool directory. If they areremoved beforebeing 
processed by the uucico(8) daemon, the copy wi II fai I . T he fi les must be readable by the 
uucico(8) daemon, and by the invoking user. 
Copy locai source filesto the spool directory. This isthe default. 
Create ali necessary directorieswhen doing the copy. This isthe default. 
If any necessary directoriesdo not exist for the desti nati on path, abort thecopy. 
Set the grade of the fi le transfer command. J obs of a higher grade are executed fi rst. G rades 
run 0 ... 9 a ... za ... z from high to low. 
Report compi etion or fai Iure of the fi le transfer by maii(l). 

Report completion or failureof the fi le transfer by maìi(l) to thenamed user on the remote 
system. 

Do not start uucico(8) daemon immediately; merely queueup the fi le transfer for later 
execution. 

Printj obi d on standard output. The job may be later canceled by passi ngthej obi d to the 
-k switch of uustat(l). It ispossibleforsomecomplexoperationsto produce more than 
onej obi d, in which case, each will beprinted on a separate line. Forexample, 

uucp sysl!"userl/fi lei s y s 2 ! "u s e r 2 /f i I e 2 " u s e r 3 

will generate two separatejobs, one for the system sysi and one for the system sys2. 
D o not prepend remote relative pathnameswith thecurrent directory. 
Turn on particular debugging types. Thefollowing typesarerecognized: abnormai, chat, 

handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 

0 nly abnormai, config, spooidir, and execute are meaningful for uucp. M ultiple types 
may begiven, separated by commas, and the - - debug option may appear multi pie ti mes A 
number may also be given, which will turn on thatmany types from theforegoing list; for 

example, - -debug 2 isequivalenttO - -debug abnormai, chat. 

Set configuration fileto use. This option may not beavailable, depending upon how uucp 
was compiled. 

Report version information and exit. 
Print a help message and exit. 



-c, - -nocopy 

-C, - - copy 

-d, - -directories 

-f , - - nodirectories 

-g grade, - -grade grade 

-m, - - mail 

-n user, - -notif y user 



■ j obi d 



-W, - - noexpand 

-x t ype, - -debug t ype 



-I file, - -config file 

-v, - -version 
- -help 



FI LES 

Thefilenamesmay bechanged at compilation ti me or by the configuration file, so theseareonly approximations. 



uuencode 




/ usr /lib/ uucp /conf ig 
/usr/ spool /uucp uucp 
/ usr / spool /uucp/ Log 
/usr/ spool /uucppublic 

SEEALSO 

mail(l), uux(l), uustat(l), uucico(8) 

BUGS 

Some of the options are dependent on thecapabilitiesof theuucico(8) daemon on the remote system. 
The -n and -mswitchesdo notwork when transferri ng a file from one remote system to another. 
Filemodesarenot preserved, exceptfortheexecutebit. T he resulting file is owned bytheuucp user. 

AUTHOR 

lan LanceTaylor (ian@airs.com) 

Taylor UUCP 1.05 



Configuration file 
spool di rectory 
uucp logfile 

Default uucp public directory 



uuencode 

uuencode— Encodea binary file 
uudecode-Decodeafilecreated by uuencode 

SYNOPSIS 

uuencode [ -m] [file ] na me 
uudecode [-0 outfile] [ file ]... 

D ESC RIPTIO N 

uuencode and uudecode areused to transmit binary files over transmission mediumsthat do not support other than simple 
ASCII data. 

uuencode readsf i 1 e (or by default the standard input) and writesan encoded version to the standard output. The encoding 
usesonly printing ASCII characters and i ncludes the mode of the fi le and theoperand name for useby uudecode. I f n a me is / 
dev/stdout, the result will bewritten to standard output. By default, the standard uu encoding format will beused. If the 
option -m isgiven on thecommand line, base64 encoding isused instead. 

uudecode transformsuuencoded files (or by default, the standard input) into theoriginal form. The resulting file isnamed 
name (or outfile if the -0 option isgiven) and will havethe mode of theoriginal fileexcept that setuid and execute bits 
are not retai ned. If outfile or name is /dev/stdout, the result will bewritten to standard output, uudecode ignoresany 
leading and trai li ng lines. The program can automati cai ly decide which of thesupported encoding schemes areused. 

EXAMPLES 

Thefollowingexamplepackagesup asourcetree, compressesi t, uuencodes it, and mailsitto a user on another system. 
When uudecode isrun on the target system, the fi le src_t ree. tar.z will becreated, which may then beuncompressed and 
extracted into theoriginal tree. 

tar cf - src_tree ] compress j uuencode src_tree.tar.Z ] mail sys! ! sys2 ! user 
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SEEALSO 

compress(l), mail(l), uucp(l), uuencode(5) 

STANDARD S 

Thisimplementation is compliant with P1003.2b/D 11. 
BUGS 

If morethan onefile is given to uudecode and the -o option isgiven or morethan onename in theencoded files isthesame, 
the result is probably not what is expected. 

Theencoded forni of thefileisexpanded by 37 percent for uu encoding and by 35 percent for base64 encoding (3 bytes 
become4 plus control information). 

HI STORY 

Theuuencode command appeared in BSD 4.0. 

uustat 

uustat— uucp status inquiry and control 
SYNOPSIS 

uustat -a 
uustat --ali 

uustat [ -eKRìMNQ ][-sS system ] [ -uU user ] [ -cC command ] [ -oy hours ] 

[ - B I i n e s ] [ --executions ] [ - -kill-all ] [ - -rejuvenate-all ][--prompt ][--mail ] 

[--notify ][--no-list ][- -system system ] [ --not-system system ] [ --user user ] 

[--not-user user ] [ --command command ] [ - -not -command command ] 

[ - -older -than hours ] [ - -younger-than h ou r s ] [ - -mail-lines li nes ] 

uustat [ -kr jobid ] [ --kill jobid ] [ --rejuvenate jobid ] 

uustat -q [ -sS system ] [ -oy hours ] [ --system system ] [ --not-system system ] 
[ - -older-than hours ] [ --younger-than hours ] 

uustat --list [ -sS system ] [ -oy hours ] [ --system system ] 

[ --not-system system ] [ --older-than hours ] [ --younger-than hours ] 

uustat -m 

uustat --status 

uustat -p 

uustat --ps 

D ESC RIFIO N 

The uustat command can display varioustypesof status information abouttheUUCP system. It can also beused to canee! 
or rejuvenate requestsmade by uucp(l) or uux(l). 

By default uustat displaysall jobsqueued up for the invoking user, asif given the - -user option with the appropriate 
argument. 



uustat 



-ali, -e, - -executions, -s, - -system, -S, -- not - system, -u, - -user, -U, --not-user, -c, --command, -C, 

o, - -oider-than, -y, - -younger-than options are given, then ali jobs that match the combined specifi ca- 



If anyof the -a, 

- - not -command, 

tions are display ed. 

The -k or --km-aii option may beused to kill off a selected group of jobs, such asall jobs more than severi daysold 
OPTIONS 

T he followi ng opti ons may be given to uustat. 

Listali queued filetransfer requests. 



-a, - -ali 
-e, - -executions 



-s system, --system system 



-S system, 

- -not-system system 



-user user 



-U user. 



-not-user user 



-eco mma n d , 

- - command c o mma n d 



-C c o mma nd , 

- -not -command command 



-o hours, 

- -older-than hours 

-y hours, 

- -younger-than hours 
-k j obi d, - -kill j obi d 



- r j obi d , 

- -rejuvenate j obi • 



List queued execution requests rather than queued filetransfer requests. Queued execution 
requests are processed by uuxqt(8) rather than uucico(8). Queued execution requests may 
be wai ti ngfor some file to betransferred from a remote system. They are created by an 
invocation of uux(l). 

Listali jobs queued up forthenamed system. These options may be specifi ed multiple 
times, in which case ali jobs forali thesystemswill belisted. If used with --list, only the 
systems named will belisted. 

List ali jobs queued for systems other than the one named. These opti ons 
may bespecified multi pletimes, in which case no jobs from anyof the specified systems will 
belisted. If used with - - list, only the systems not named will belisted. These opti ons 
may not beused with -s or - - system. 

Listali jobs queued up forthenamed user. These options may bespecified multi pie times, 
in which case ali jobs for ali the users will belisted. 

Listali jobs queued up for users other than the one named. These options may bespecified 
multipletimes, in which case no jobs from anyof the specified userswill belisted. These 
options may not beused with -uor --user. 

Listali jobs requesting the execution of thenamed command. If command is all this wi II 

list ali jobs requesting the execution of some command (asopposed to simply requesting a 

filetransfer). These options may bespecified multipletimes, in which case all jobs 

requesting any of the commands will belisted. 

Listali jobs requesting execution of some command other than thenamed 

command, or, if command ìsall, list all jobs that simply request a file transfer (asopposed 

to requesting the execution of some command). These opti ons may bespecified multiple 

times, in which case, no job requesting one of the specified commands will belisted. These 

options may not beused with -cor - -command. 

Listali queued jobs older than the given number of hours. If used with - - list, only 
systems whoseoldest job isolderthan thegiven number of hours will belisted. 
Listali queued jobsyounger than thegiven number of hours. If used with - - list, 
only systems whoseoldest job isyounger than thegiven number of hours will be 
listai. 

Kill thenamed job. Thejob ID isshown by the default output format, aswell as by the - j 
or - - jobid option to uucp(l) or uux(l). A job may only bekilled by the user who created 
thejob, or by theUUCP administrator or thesuperuser. The -k or - -km options may be 
used multipletimeson the command lineto kill several jobs. 
Rejuvenate the named job. Thiswill mark itashavingbeen invoked atthecurrent 
ti me, affetti ng the output of the -o, - - oider-than, -y, or - - younger-than optionsand 
preserving itfrom any automated cleanup daemon. Thejob ID isshown by the default 
output format, aswell as by the - j or - - jobid options to uucp(l) or uu(l). A job may only 
berejuvenated by the user who created thejob, or by theUUCP administrator or the 
superuser. The -r or - -rejuvenate optionsmay beused multipletimeson thecommand 
lineto rejuvenate several jobs. 
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-q, - -list 



-m, - -status 

-P, - -ps 

-i, - -prompt 

-K, --kill-all 

-R, - - re] uvenate-all 
-M, - - mail 



-N, - -notify 

-W, - - comment 

-Q, - - no -list 

-x t ype, - -debug t ype 



-I file, - -config file 

-v, - -version 
- -help 

EXAMPLES 

uustat -ali 



uustat -executions 



D i splay the status of commands, executions, and conversationsfor ali remote systemsfor 

which commandsor executions are queued. The -s, --system, -s, - -not-system, -o, -- 

oider-than, -y, and - -younger-than optionsmay beused to restrict the systems that are 

listed. Systemsfor which no commands or executions are queued will never belisted. 

D isplay the status of conversations for ali remote systems. 

D i splay the status of ali processes holding uucp lockson systems or ports. 

Foreach I isted job, prompt whetherto kill thejob ornot. If the first characterof the input 

lineisy ory, thejob will be ki lied. 

Automatically kill each listed job. Thiscan beuseful for automatic cleanup scripts, in 

conjunction with the - -mail and - -notify options 

Automatically reju venate each listed job. Thismay not beused with --kiii-aii. 

Foreach listed job, send mail to theUU CP administrator. If thejob iskilled (dueto - - 

kiii-aii or - - prompt with an affirmativeresponse), the mail will indicate that. A comment 

specified by the - - comment option may beincluded. If thejob isan execution, theinitial 

porti on of its standard input will beincluded in the mail message; thenumber of linesto 

include may be set with the --maii-iines option (the default is 1 00). I f the standard input 

contai ns nuli characters, it isassumed to bea binaryfileand isnot included. 

Foreach listed job, send mail to the user who requested thejob. The mail isidentical to that 

sent by the -m or - -man options. 

Specify a comment to beincluded in mail sent with the -m, - -man, -n, or - -notify 
options. 

Do not actually list thejob, but only takeany actions indicated by the -±, --prompt, -k, -- 

kill-all, -M, - -mail, -N, Or - -notify Options. 

Tum on particular debugging types. Thefollowing typesarerecognized: abnormai, chat, 

handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 
0 nly abnormai, config, spooldir, and execute are meaningful for uustat. 

M ultiple types may begiven, separated by commas, and the - -debug option may appear 
multipletimes. A number may also begiven, which will tum on that many types from the 

foregoing list; for example, - -debug 2 isequivalenttO - -debug abnormai, chat. 

Set configuration fileto use This option may not beavailable, depending upon how uustat 
was compiled. 

Report version information and exit. 
Print a help message and exit. 



D isplay status of ali jobs. A sam pie output lineisasfollows: 

bugsA027h bugs ian 04-01 13:50 Executing rmail ian@airs.com (sending 1283 
bytes) 

Theformat is 

jobid system user queue-date command (size) 

The jobid may be passed to the - - km or - -rejuvenate options. The size indicates how 
much data isto betransferred to the remote system, and is absent for a file receive request. 

The --system, - -not-system, - -user, - -not -user, - -command, -- not -command, --older- 

than, and - -younger-than optionsmay beused to control which jobs are listed. 
D isplay status of queued up execution requests. A sample output lineisasfollows: 

bugs bugslian 05-20 12:51 rmail ian 

Theformat is 

system requestor queue-date command 

The --system, - -not-system, --user, --not-user, - -command, -- not -command, --older- 

than, and - -younger-than optionsmay beused to control which requests are listed. 



uux 




uustat -list D isplay status forali systemswith queued-up commands. A sample output line isasfollows: 

bugs 4C (1 hour) 0X (0 secs) 04-01 14:45 Dial failed 

This indicates the system, thenumber of queued commands, theageof the oldest queued 
command, the number of queued locai executions, the ageof theoldest queued execution, 
the date of the last conversation, and the status of that conversation. 

D isplay conversation status forali remote system s. A sample output line isasfollows: 

bugs 04-01 15:51 Conversation complete 

This i ndicates the system, the date of the last conversati on, and the status of that conversa- 
tion. If the last conversation failed, uustat will indicate how many attempts havebeen 
madeto cali the system. If the retry period iscurrently preventi ng Calisto that system, 
uustat also displaysthetimewhen thenextcall will bepermitted. 

D isplay the status of ali processes holding uucp locks. The output format issystem- 
dependent, as uustat simply invokesps(l) on each process holding a lock. A sampleoutput 
li ne isasfollows: 

uustat -command rmail -older-than 168 -kill-all -no-list -mail -notify - 
comment "Queued for over 1 week" 

Thiswill kill ali rmaii commands that have been queued upwaiting for delivery for over 
oneweek (168 hours). For each such command, mail will besent both to theUU CP 
administrator and to the user who requested the mail execution. The mail messagesent 
will include the stri ng given by the - - comment option. The - - no -list option preventsany 
of thejobsfrom being listed on the terminal, so any output from the program will be errar 
messages. 

FILES 

Thefilenamesmay bechanged at compilation ti me or by theconfiguration file, so theseareonly approximations. 
/usr/iib/uucp/config Configuration file 
/usr/spooi/uucpuucp spool directory 

SEE ALSO 

ps(l), rmail(l), uucp(l), uux(l), uucico(8), uuxqt(8) 

AUTHOR 

lan LanceTaylor (ian@airs.com) 

Taylor UUCP 1.05 

UUX 

uux— Remote command execution over uucp 
SYNOPSIS 

uux [ opti o n s ] command 

D ESC RIFIO N 

The uux command isused to execute a command on a remote system, orto execute a command on the locai system using 
filesfrom remote systems. Thecommand isnot executed immediately; therequest is queued until theuucico(8) daemon 
cai Is the system and executesit. The daemon isstarted automatically unlessoneof the -r or - -nouucico optionsis given. 



uustat -status 



uustat -ps 
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Theactual command execution isdonebytheuuxqt(8) daemon. 

Fileargumentscan begathered from remote system sto theexecution system, ascan standard input. Standard output may be 
directed to afileon a remote system. 

The command namemay bepreceded by a system namefollowed by an exclamati on point if it isto beexecuted on a remote 
system. An empty system nameistaken as the locai system. 

Each argumentthat contai nsan exclamation point istreated asnamingafile Thesystem thatthefileison isbeforethe 
exclamation point, and thepathnameon that system followsit. An empty system nameistaken as the locai system; thismust 
beused to transfer a file to a command bei ng executed on a remote system. If thepath isnot absolute, it wi 1 1 beappended to 
the current working di rectoryon the locai system; the result may not bemeaningful on the remote system. A pathnamemay 
begin with -/, in which caseit is relative to theuucp public directory (usuai ly /usr/spooi/uucppubiic) on the appropriate 
system. A pathnamemay begin with "name/, in which caseit is relative to the home directory of thenamed user on the 
appropriate system. 

Standard input and output may be redi rected as usuai; thepathnamesused may contai n exclamation pointsto indicate that 
they are on remote system s. N ote that the redi rection characters must be quoted so that they are passed to uux rather than 
interpreted bytheshell. Append redirection (») doesnotwork. 

Ali specified filesaregathered together into a single directory before execution of thecommand begins. This meansthat each 

fi le must havea disti net base name. Forexample, 

uux 'sysHdiff sys2! "user"! /foo sys3! "user2/foo >!foo.diff 1 

will fail becauseboth fileswill becopied to sysi and stored under the name foo. 

Argumentsmay be quoted by parenthesesto avoid interp retati on of exclamation poi nts. This isuseful when executing the 
uucp command on a remote system. 

OPTIONS 

T he followi ng opti ons may be gi ven to uux. 

-, -p, --stdin Read standard inputand use itasthe standard inputfor the command to beexecuted. 

-e - -nocopy Do notcopy locai fi lesto the spool directory. This is the default. If they areremoved before 

bdng processed by theuucico(8) daemon, the copy will fail. The fi les must bereadableby 

theuucico(8) daemon, aswell asbytheinvoker of uux. 
-c, - -copy Copy locai filesto the spool directory. 

-ì, - - link Link locai fi les into the spool directory. If afilecan not belinked becauseit ison adifferent 

device itwill becopied unlessoneof the -c or - -nocopy optionsalso appears (in other 
words, useof -- link switches the default from --nocopy to --copy). If thefilesarechanged 
before being processed by theuucico(8) daemon, thechanged versionswill beused. The 
fi les must bereadableby the uucico(8) daemon, aswell as by the i nvoker of uux. 

-g grade, --grade g r ad e Set the grade of the file transfer command. J obs of a higher grade are executed fi rst. G rades 
run 0 ... 9 a ... za ... z from high to low. 

-n, - -notification=no Do notsend mail about the status of the job, even if itfails. 

-z, --notification=error Send mail about the status of the job if an errar occurs. Formanyuuxqt daemons, 
including theTaylor uucp uuxqt, this isthe default action; forthose - - 
notification=er r or will haveno effect. H owever, some uuxqt daemons will send mail if 
thejob succeedsunlessthe - -notification=err-or option isused, and someother uuxqt 
daemonswill notsend mail if thejob fails unless the - -notification=err-or option isused. 

-r, --nouucico Do not start the uucico(8) daemon immediately; merely queueup the execution requestfor 

later processing. 



uux 



-j, --jobid P ri nt jobids on standard output. A jobidwill begenerated foreach file copy operation 

required to perform the operation. These file copi es may becanceled by passing the jobid 
to the --kiiiswitch of uustat(l), which will maketheexecution impossibleto complete. 

-a address, Report job status to thespecified e-mai I address. 

- -requestor addr ess 

-x type, - -debug type Turn on parti cular debugging types. Thefollowing types are recognized: abnormai, chat, 

handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 

Only abnormai, config, spooidir, and execute are meaningful foruux. M ultipletypes 
may begiven, separated by commas, and the - - debug option may appear multi pie ti mes. A 
number may also be given, which will turn on thatmany types from theforegoing list; for 

example, - -debug 2 isequivalenttO --debug abnormai, chat. 

-1 file, - -config file Set configuration file to use This option may not be avai labi e, dependi ng upon how uux 
wascompiled. 

-v, --version Report version information and exit, 

--heip Print a help messageand exit. 

EXAMPLES 

uux -z - sysiirmaii useri— Execute the command rmaii useM on the system sysi , giving it as standard input 
whatever is given to uux as standard input. If afailureoccurs, send a messageusing maii(l). 

uux 'diff -c sysi ! "useri /fiiei sys2 ruser2/fiie2 > !f ile . diff — Fetch the two named files from system sysi and 
system sys2 and execute diff, putti ng the result in file, diff in thecurrent directory. The current directory must be 
writableby theuuxqt(8) daemon for this to work. 

uux 'sysnuucp "usen/fiiei (sys2!"user2/f ìie2) '— Execute uucp on the system sysi copying f ilei (on system 
sysi) to sys2. This illustrates the use of parenthesesfor quoting. 

RESTRICTIONS 

The remote system may not permit you to execute certain commands. M any remote systems only permit theexecution of 

rmail and rnews. 

Some of the options are dependenton the capabilities of theuuxqt(8) daemon on the remote system. 
FILES 

Thefilenamesmay bechanged at compilation ti me or by the configuration file, so these are only approximations. 
/usr/iib/uucp/config Configuration file 

/usr/spooi/uucpuucp spool directory 

/usr/spool/uucp/Log uucp log file 

/usr/spooi/uucppubiic D efault uucp public directory 

SEE ALSO 

mail(l), uustat(l), uucp(l), uucico(8), uuxqt(8) 

BUGS 

Files can not bereferenced across multiple systems 

Too many jobids are output by - - jobid, and thereisno good way to canee! a locai execution requiring remote files. 



AUTHOR 

lan LanceTaylor (ian@airs.com) 
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uuxqt 



uuxqt— uucp execution daemon 
SYNOPSIS 

uuxqt [ opti o n s ] 

D ESC RIFIO N 

The uuxqt daemon executes commands requested by uux(l) from either the locai system orfrom remote system s. It isstarted 
automatically by theuucico(8) daemon (unlessuucico(8) isgiven the -q or - -nouuxqt option). 

There isnormally no need to run thiscommand becauseit will beinvoked by uucico(8). H owever, it can beused to provide 
greater control over the processi ng of the work queue. 

M ulti pie invocati onsof uuxqt may berun at once, as controlied by themax-uuxqts confi guration command. 
OPTIONS 

T he followi ng opti ons may be gi ven to uuxqt : 

-c command, --command command 0 nly execute requestsfor the specified command. For example, 

uuxqt -command mail 

-s system, --system system 0 nly execute requests originating from the specified system. 

-x type, --debug type Turn on parti cular debugging types. The following types are recognized: abnormai, 

chat, handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, 
outgoing. 0 nly abnormai, config, spooldir and execute are meaningf ul for 

uuxqt. M ultiple types may begiven, separated by commas, and the - -debug option 
may appear multi pie ti mes. A number may also begiven, which will turn on that 
many types from the foregoing list; for example, - -debug 2 isequivalentto - -debug 

abnormai, chat. 

The debugging output issent to the debugging file usually /usr/spooi/uucp/ 

Debug, /usr/spool/uucp/DEBUG, Or /usr/spool/uucp/ .Admin/audit. locai. 

-1 file, --config Set configuration file to use. T his option may not be avai labi e, dependi ng upon how 

uuxqt wascompiled. 
-v, --version Report version information and exit, 

--heip Print a help messageand exit. 

FILES 

Thefilenamesmay bechanged at compilation ti me or by the configuration file, so theseareonly approximations. 

/usr/iib/uucp/config Configuration file 

/usr/spooi/uucpuucp spool directory 

/usr/spool/uucp/Log uucp log file 

/usr/spooi/uucppubiic D efault uucp public directory 

/usr/spooi/uucp/Debug D ebugging file 

SEE ALSO 

uucp(l), uux(l), uucico(8) 

AUTHOR 

lan LanceTaylor (ian@airs.com) 

Taylor UUCP 1.05 



* [T] 

w 

w— Present who users are and what they are doing 
SYNOPSIS 

w [ -hin] [-user ] 

D ESC RIPTIO N 

Thew utility printsa summary of thecurrent activity on the system, includi ng what each user is doing. The first linedisplays 
thecurrent timeof day, how long the system hasbeen running, thenumber of users logged into the system, and theload 
averages. Theload averagenumbersgi ve thenumber of jobsin therun queue averaged over 1, 5, and 15 minutes. 

T he fields output aretheuser'slogin name, the nameof the terminal the user ison, thehostfrom which the user is logged 
in, the ti me the user logged on, the ti me si nce the user lasttyped anything, and the name and argumentsof thecurrent 
process. 

The opti ons are as follows: 

-h Suppresstheheading 

-i Output is sorteci by idletime 

-n Show network addressesas numbers 

-w Interpretaddressesand attemptto display them symbolically 

If a usernameisspecified, the output is restri cted to that user. 
FILES 

/var/run/utmp List of users on the system 
SEEALSO 

who(l), f inger(l), ps(l), uptime(l), 

BUGS 

Thenotion of thecurrent process ismuddy. Thecurrent algorithm is "the highest numbered process on the terminal that is 
not ignori ng interrupts, or, if there isnone, the highest numbered process on the terminal." Thisfails, for example, in criticai 
sectionsof programs like the shell and editor, orwhen faulty programs running in the background fork and fail to ignore 
interrupts. (In caseswhereno process can befound, w printsa period.) 

TheCPU timeisonlyan estimate; in particular, if someoneleaves a background process running after loggingout, the 
person currently on that terminal ischarged with thetime 

Background processes are not shown, even though they account for much of the load on the system. 

Sometimesprocesses, typically thosein the background, areprinted with nuli or garbaged arguments. In thesecases, the 
nameof the command isprinted in parentheses. 

Thew utility does not know aboutthenew conventionsfor detection of background jobs. Itwill sometimesfind a back- 
ground job instead of theright one. 

COMPATIBILITY 

The-f, -ì, -s, and -wflagsareno longer supported. 

HI STORY 

Thew command appeared in BSD 3.0. 

BSD 4, 6Junel993 
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wall 

waii— W rite a message to users 
SYNOPSIS 

wall [file] 

D ESC RIFIO N 

waii displaysthecontentsof fileor, by default, its standard input, on theterminalsof ali currently logged in users. 

Only thesuperuser can writeon theterminalsof users who havechosen to deny messages or are using a program that 
automati cai ly denies messages. 

SEEALSO 

mesg(l), talk(l), write(l), shutdown(8) 

HI STORY 

A waii command appeared in AT&T v7. 

Linux 0.99, 8 March 1993 

wc 

wc— Printthenumber of bytes, words, and linesin files 
SYNOPSIS 

wc [-clw] [--bytes] [--chars] [--lines] [--words] [--help] [--version] [file...] 

D ESC RIFIO N 

Thismanual page documents the GN U version of wc. wc countsthenumber of bytes, whitespace-separated words, and 
newlines in each given file, or the standard input if none are given or when afilenamed - isgiven.lt printsonelineof 
countsfor each file, and if the file was given asan argument, it pri nts the fi lenamefollowing the counts. If morethan one 
fi lenameis given, wc printsafinal linecontainingthecumulative counts, with the filmarne total. The counts are pri nted in 
theorder lines, words, bytes. 

By default, wc pri nts ali three counts Opti ons can specify that only certain counts beprinted. Optionsdo notundo others 
previ ously given, so wc - - bytes --words printsboth the byte counts and the word counts. 

OPTIONS 

-c, - -bytes, - -chars 
-w, - -words 
-1, - -lines 
- -help 
- - version 

GNU TextUtilities 



Pri nt only the byte counts. 

Printonlytheword counts. 

Print only the newline counts. 

Print a usage message and exit with a non-zero status. 

Print version information on standard output, then exit. 



whereis 



whereis 

whereis— Locate the binary, source, and manual pagefilesforacommand 
SYNOPSIS 

whereis [ - bmsu ][-BMS directory... -f ] filename ... 

D ESC RIFIO N 

whereis locates source/binary and manuals sectionsfor specified files. Thesupplied names are first stripped of leading 
pathname components and any (single) trai li ng extension of the forni . ext, for example, .c. Prefixesof s. resulti ngfrom use 
of source code control arealso dealtwith. whereis then attemptsto locate thedesired program in a list of standard Linux 
places: 

/bin 

/usr/bin 
/etc 

/usr/etc 

/sbin 

/usr/sbin 

/usr/games 

/usr/games/bin 

/usr/emacs/etc 

/usr/lib/eniacs/19.22/etc 

/usr/lib/emacs/19.23/etc 

/usr/lib/emacs/19.24/etc 

/usr/lib/emacs/19. 25/etc 

/usr/lib/emacs/19.26/etc 

/usr/lib/emacs/19. 27/ etc 

/usr/lib/emacs/19.28/etc 

/usr/lib/emacs/19. 29/ etc 

/usr/lib/emacs/19. 30/ etc 

/usr/TeX/bin 

/usr/tex/bin 

/usr/interviews/ bin/ LINUX 

/usr/bin/X11 

/usr/X11 /bin 

/usr/X11R5/bin 

/usr/X11R6/bin 

/usr/X386/bin 

/usr/local/bin 

/usr/local/etc 

/usr/local/sbin 

/usr/local/games 

/usr/local/games/bin 

/usr /locai/ emacs /etc 

/usr/local/TeX/bin 

/usr/local/tex/bin 

/usr/local/bin/X11 

/usr/contrib 

/usr/hosts 

/usr/include 

/usr/g++-include 
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OPTIONS 

-b Search only for binarie. 

-m Search only for manual sections. 

-s Search only for sources. 

-u Search for unusual entries. A fileissaid to beunusual if it doesnot haveone entry of each requested type. Thus 

whereisnn-mnn-unn* asks for thosefi lesin the current di rectory which haveno documentation. 
- b C hange or otherwi se li mit the places where whereis searches for bi naries. 
-m Changeorotherwiselimittheplaceswherewhereis searches for manual sections. 
- s C hange or otherwise li mit the places where whereis searches for sources. 

-f T ermi nate the last directory list and signals the start of filenames; must beused when any of the -b, -m, or -s 
optionsare used. 

EXAMPLE 

Find ali fi lesin /usr/bin that arenot documented in /usr/man/mani with sourcein /usr/src: 

example% ed /usr/bin 

example% whereis -u -M /usr/man/man1 -S /usr/src -f * 

FILES 

/{bin,sbin,etc} 

/usr/{lib,bin, old, new, locai, games, include, et c.src, man, sbin, 
X386, TeX, g++-include} 

/usr /locai/ {X386,TeX,X1 1 , include, lib, man, etc,bin, games, emacs} 

SEEALSO 

chdir(2V) 

BUGS 

Since whereis uses chdir(2V) to run faster, patnnames given with the -m, -s, or -b must be full ; that is, they must begin 
with a /. 

8 May 1994 

write 

write— Send a messageto another user 
SYNOPSIS 

write user [t t y na me ] 

DESCRIPTION 

write allowsyou to communi cate with other users by copying linesfrom your terminal to theirs. 
When you run the write command, the user you arewriting to getsa messageof theform: 

Message from yourname@yourhost on yourtty at hh:mm ... 

Any further linesyou enterwill be copi ed to the specified user's terminal. If the other user wantsto reply, he or shemust run 
write aswell. 

When you aredone, typean end-of-fileor interrupt character. The other user wi II see the message eof, indicating that the 
conversati on isover. 
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You can prevent people(other than the superuser) from writing to you with themesg(l) command. Somecommands, for 
example, nroff(l) and pr(l), may disallow writing automatically, so that your output isn't overwritten. 

If the user you wantto writeto islogged in on more than one terminal, you can specify which terminal to writeto Py 
specifying the terminal nameasthesecond oper and to thewrite command. Alternati vely, you can letwnte select oneof 
the termi nals— itwill pick the one with theshortest idletime Thus, if the user islogged in atwork and also dialed up from 
home, themessagewill go to the right place. 

Thetraditional protocol for writing to someone is that the stri ng -o, either at the end of a line or on a linePy itself, means 
that it's the other person'sturn to talk. The stri ngoo means that the person Peli eves the conversation to Peover. 

SEE ALSO 

mesg(l), talk(l), who(l) 

HI STORY 

A write command appeared in Version 6 AT&T UNIX. 

12 M ardi 1995 

x1 1 perf 

xiiperf— Xll server performance test program 
SYNTAX 

xllperf [ -option ... ] 

DESCRIPTION 

Thexiiper-f program runsoneor more performance tests and reportshow fast an x server can executethetests. 

M any graphics Penchmarks assume that the graphics device is used to display the output of a si ngle fancy graphics applica- 
tion, and that the user getshiswork doneon som e other device, li ke a terminal. Such Penchmarks usuai ly measuredrawing 
speed for lines, polygons, text, and so on. 

Becauseworkstations are not used asstandalonegraphicsengines, Put as su per- termi nals, xnperf measureswindow 
management performance aswell astraditional graphics performance, xnperf includesPenchmarksforthetimeittakesto 
create and map Windows (aswhen you start up an application); to map a preexistingset of Windows onto thescreen (aswhen 
you deiconify an application or pop up a menu); and to rearrange Windows (aswhen you slosh Windows to and fra tryingto 
find theoneyou want). 

xnperf also measures graphics performance for operationsnot normally used in standalone graphics di splays, Put are 
nonetheless used frequently Py x applicati ons. Such operations include copypiane (used to map Pitmapsinto pixels), 
scroiiing (used in text wi ndows), and variousstipplesand tiles(used for CAD and color halftoning, respectively). 

xnperf should Peused to analyze particular strengths and weaknesses of servers, and ismostuseful to a server wri ter who 
wantsto analyze and im prove a server, xnperf ismeant to comprehensively exercisejust aPout every Xll operati on you can 
perform; it doesnot purportto Pe a representati ve sampleof the operati ons that Xll appi ications actually use. Although it 
can Peused asa Penchmark, itwaswritten and isintended as a performance testi ng tool. 

Assuch, xnperf does not whittle down measurementsto asingleHexstonesor Mexops numPer. Weconsider such numPers 
to Peuninformativeat Pestand misleadingatworst. Some servers that are very fast for certain applicationscan Peveryslow 
for others. N o single numPer or small set of numPers is suffici ent to characterizehow an x implementation will perform on 
ali applications. However, Py knowledgeof your favorite application, you mayPeaPleto use the numPers xnperf reportsto 
predict its performance on agiven x implementation. 
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That said, you might also wantto look at xnperfcomp(l), a program to compare the outputs of different xnperf runs. You 
provide a listof fi les contai ni ng resultsfrom xnperf, and it laysthem out in a ni ce tabular format. 

Forrepeatableresults, xnperf should berun usinga locai connection on afreshly started server. The default configurati on 
runseach test fi ve ti mesi n orderto seeif each trial takes approximately thesameamount of ti me. Strangeglitches should be 
examined; if nonrepeatable, you might chalk them up to daemonsand network traffic. Each trial isrun for fiveseconds, in 
orderto reduce random timedifferences. Thenumber of objects processed per second isdisplayed to threesignificant digits, 
but you'll belucky on most UN IX systemsif thenumbersareactually consistentto two digits. xnperf movesthecursor out 
of the test window; you should becareful notto bump the mouse and moveit back into thewindow. (A prizeto peoplewho 
correctly explain why!) 

Beforerunning a test, xnperf determi neswhat the round trip ti me to the server is, and facto rsthis out of the final timing 
reported. It ensures that the server hasactually performed thework requested by fetchinga pixel back from the test window, 
which meansthat servers tal ki ng to graphics accelerators can't claim that they aredone, while in the meantimetheaccelera- 
tor ispainting madly. 

By default, xnperf automatically cali brates thenumber of repetitionsof each test, so that each should take approximately 
thesamelength ottime to run across servers ofwidely differì ng speeds. H owever, becauseeach test must berun to comple- 
ti on at least once someslow servers may take a very long ti me, particularly on thewindow movi ng and resi zing tests, and on 
the are drawing tests. 

Ali timing repo rts are f o r th e sm al I est object involved. For example, thelinetestsuseapoiyLine requestto paint several lines 
at once, but report how many lines per second the server can paint, not how many PoiyLine requests per second. Text tests 
paint a line of characters, but report on thenumber of characters per second. Somewindow tests map, unmap, ormovea 
single parent window, but report on how many children Windows per second the server can map, unmap, ormove. 

Thecurrent program ismostly the responsi bility of Joel M cCormack. It is based upon the xnperf developed by Phil 
Karlton, Susan Angebranndt, Chris Kent, M ary Walker, and Todd N ewman, who wanted to assess performance differences 
between vari ous servers. Several tests were added in orderto writeand tunethePM AX (D E C Station 3100) servers. Fora 
general releaseto theworld, xnperf wasrewritten to easemakingeomparisons between widely varying machines, to cover 
most important (and unimportant) x funzionali ty, and to exerci se graph i cs o perati ons i n as many different orientationsand 
alignments as possi ble 



0PTI0NS 

xnperf issolelyxiib based, and acceptsthefollowingoptions: 
-display h o s t : d p y Specifi es which display to use 



-range 

<t e s t 1 > [ , <t e s 1 2 > ] 



-labels 



-ali 



-f g c o I o r - o r ■ p i xe I 
-bg col or-or-pi xel 
-clips default 



-time <s> 



-sync 



-repeat <n> 



-pack 



Runs the tests in synchronousmode. N ormally only useful for debugging xnperf. 
Runs rectangle tests so that they pack rectangles right next to each other. This makes it easy 
to debug server code for stipples and ti les; if the pattern looksugly, you'vegot alignment 
problems. 

Repeatseach test n times(by default each test isrun fivetimes). 

Specifi eshow long in secondseach test should berun (default 5 seconds). 

Runs ali tests. Thismaytakeawhile. 

Runs ali the tests starti ng from the specified namet est 1 until thenamet est 2, tests The 
testnames should beone of the opti ons starti ng from -dot. For example, -range ìineioo 
will perform the tests from thelOO pixel line test, and go on till the last test; -range 

Iine100,dline10 will do thetestsfrom line100 tO dline10. 

G enerates just the descri ptive labels for each test specified. See xi 1 perf comp for more 
details. 

Specifi es the foreground color or pixel valueto use. 
Specifi es the background color or pixel valueto use. 
Default numberof clip Windows. 
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-ddbg color-or-pixel 

-rop <rop0 rop1 . . .> 

-pm <pmO pml . . .> 

-depth <dept tt> 
-vclass <v c I a s s > 

-reps <n> 

-subs <s 0 si . . .> 

-v1 .2 
-v1 .3 

-su 

-bs 

<backing_store_hint> 

-dot 

-recti 

-rect10 

-rect100 

-rect500 

-srecti 

-srecti 0 

-srect100 

-srect500 

-osrectl 

-osrect10 

-osrect100 

-osrect500 

-tilerectl 

-tilerect10 

-tilerect100 

-tilerect500 

-oddsrectl 

-oddsrect10 

-oddsrect100 

-oddsrect500 

-oddosrectl 

-oddosrect10 

-oddosrect100 

-oddosrect500 

-oddtilerectl 

-oddtilerect10 



Specifi es the color or pixel value to use for drawi ng the odd segments of a DoubieDashed 
lineor are. Thiswill default to thebg color. 

Use specifi ed raster ops (default isGXcopy). Thisoption only affeets graphics Penchmarks in 
which the graphics function isactually used. 

Use specifi ed pi anemasks (default is "0). Thisoption only affeets graphics Penchmarks in 
which theplanemask isactually used. 

Use a visual with <depth> planesper pixel. (Default is the default visual.) 

Use a visual with Of Class <v c a s s >. <vcl a s 5 > can bestaticGray, GrayScale, 
StaticColor, PseudoColor, TrueColor, Or DirectColor. (D efault ÌS the default visual). 

Specify the repeti tion count. (Default isnumPerthattakesapproximately fiveseconds.) 
Specify thenumPer of suP Windows to use in theWindow tests. Default is 4, 16, 25, 50, 75, 
100, and 200. 

Perform only xnpert version 1.2 tests usi ng versi on 1.2 semantics. 

Perform only xnpert version 1.3 tests usi ng version 1.3 semantics. 

Set thesave_under window attriPuteto True on ali Windows created by xnperf. Default is 

False. 

Set thebacking_store window attriPuteto thegiven value on ali Windows created by 

xllperf. <backing_store_hint> Can PewhenMapped Or Always. D efault ÌSNotUsef ul. 

Dot. 

lxl solid-filled rectangle. 
10x10 solid-filled rectangle. 
100x100 solid-filled rectangle. 
500x500 solid-filled rectangle. 
lxl transparent stippled rectangle, 8x8 stipple pattern. 
10x10 transparent stippl ed rectangle, 8x8 stipple pattern. 
100x100 transparent stippled rectangle, 8x8 stipple pattern. 
500x500 transparent stippled rectangle, 8x8 stipple pattern, 
lxl opaque stippled rectangle, 8x8 stipple pattern. 
10x10 opaque stippled rectangle, 8x8 stipple pattern. 
100x100 opaque stippled rectangle, 8x8 stipple pattern. 
500x500 opaque stippled rectangle, 8x8 stipple pattern, 
lxl tiled rectangle, 4x4 tile pattern. 
10x10 ti led rectangle, 4x4 ti le pattern. 
100x100 tiled rectangle 4x4 tilepattern. 
500x500 tiled rectangle, 4x4 tilepattern. 
lxl transparent stippled rectangle, 17x15 stipple pattern. 
10x10 transparent stippled rectangle, 17x15 stipple pattern. 
100x100 transparent stippled rectangle, 17x15 stipple pattern. 
500x500 transparent stippled rectangle, 17x15 stipple pattern, 
lxl opaque stippled rectangle, 17x15 stipple pattern. 
10x10 opaque stippled rectangle, 17x15 stipple pattern. 
100x100 opaque stippled rectangle, 17x15 stipple pattern. 
500x500 opaque stippled rectangle, 17x15 stipple pattern, 
lxl tiled rectangle, 17x15 tilepattern. 
10x10 tiled rectangle, 17x15 tilepattern. 
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oddtilerectl 00 


100x100 ti 1 ed rectangle 17x15 ti le pattern. 


oddtilerect500 


500x500 tiled rectangle 17x15 tilepattern. 


bigsrectl 


lxlstippled rectangle, 161x145 stipple pattern. 


bigsrect10 


10x10 stippled rectangle, 161x145 stipple pattern. 


bigsrect100 


100x100 stippled rectangle, 161x145 stipple pattern. 


bigsrect500 


500x500 stippled rectangle, 161x145 stipple pattern. 


bigosr-ectl 


lxl opaque stippled rectangle, 161x145 stipple pattern. 


bigosrect10 


10x10 opaque stippled rectangle 161x145 stipple pattern. 


bigosrect100 


100x100 opaque stippled rectangle, 161x145 stipple pattern. 


bigosrect500 


500x500 opaque stippled rectangle, 161x145 stipple pattern. 


bigtilerectl 


lxl tiled rectangle, 161x145 tilepattern. 


bigtilerect10 


10x10 tiled rectangle, 161x145 tilepattern. 


bigtilerectl 00 


100x100 tiled rectangle 161x145 tilepattern. 


bigtilerect500 


500x500 tiled rectangle 161x145 tilepattern. 


eschertilerectl 


lxl tiled rectangle, 215x208 tilepattern. 


eschertilerectl 0 


10x10 tiled rectangle, 215x208 tilepattern. 


esc hert ile recti 00 


100x100 tiled rectangle 215x208 tilepattern. 


eschertilerect500 


500x500 tiled rectangle 215x208 tilepattern. 


seg1 


1-pixd thin linesegment. 


seg10 


10-pixel thin linesegment. 


seg100 


100-pixel thin linesegment. 


seg500 


500-pixel thin linesegment. 


seg100c1 


100-pixel thin linesegment (1 obscuring rectangle). 


seg100c2 


100-pixel thin linesegment (2 obscuring rectangles). 


seg100c3 


100-pixel thin linesegment (3 obscuring rectangles). 


dseg10 


10-pixel thin dashed segment (3 on, 2 off). 


dseg100 


100-pixel thin dashed segment (3 on, 2 off). 


ddsegl 00 


100-pixel thin double-dashed segment (3 fg, 2 bg). 


hseg10 


10-pixel thin horizontal linesegment. 


hseg100 


100-pixel thin horizontal linesegment. 


hseg500 


500-pixel thin horizontal linesegment. 


vseg10 


10-pixel thin vertical linesegment. 


vseg100 


100-pixel thin vertical linesegment. 


vseg500 


500-pixel thin vertical linesegment. 


whsegl 0 


10-pixel wide horizontal linesegment. 


whsegl 00 


100-pixel wide horizontal linesegment. 


whseg500 


500-pixel wide horizontal linesegment. 


wvsegl 0 


10-pixel wide vertical linesegment. 


wvsegl 00 


100-pixel wide vertical linesegment. 


wvseg500 


500-pixel wide vertical linesegment. 


linei 


1-pixd thin (width 0) line. 


line10 


10-pixel thin line. 


line100 


100-pixel thin line 


line500 


500-pixel thin line 
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-dlinel 0 
-dlinel 00 
-ddline100 
-wlinel 0 
-wlinel 00 
-wline500 
-wdlinel 00 
-wddline100 
-orectl 0 
-orectl 00 
-orect500 
-worectl 0 
-worectl 00 
-worect500 
-circlel 
-circle10 
-circle100 
-circle500 
-dcircle100 
-ddcircle100 
-wcircle10 
-wcircle100 
-wcircle500 
-wdcirclel 00 
-wddcirclel 00 
-pcircle10 
-pcircle100 
-wpcirclel 0 
-wpcirclel 00 
-f circlel 
■ f circlel 0 
-f circle100 
-f circle500 
-f cpcirclel 0 
-f cpcircle100 
-f spcircle10 

-f spcircle100 

-ellipse10 

-ellipse100 

-ellipse500 

-dellipse100 

-ddellipse100 

-wellipsel 0 



10-pixel thin dashed li ne {3 on, 2 off). 

100-pixel thin dashed I ine (3 on, 2 off). 

100-pixel thin douPle-dashed line (3 fg, 2 Pg). 

10-pixel line, line width 1. 

100-pixel line, linewidth 10. 

500-pixel line, linewidth 50. 

100-pixel dashed line, linewidth 10 (30 on, 20 off). 

100-pixel douPle-dashed line, linewidth 10 (30 fg, 20 bg). 

10x10 thin rectangle outli ne. 

100-pixel thin verti cai linesegment. 

500-pixel thin verti cai linesegment. 

10x10 wide rectangle outline 

100-pixel wide vertical linesegment. 

500-pixel wide vertical linesegment. 

1-pixel diameter thin (line-width 0) circle. 

10-pixel diameter thin circle. 

100-pixel diameter thin circle. 

500-pixel diameter thin circle. 

100-pixel diameter thin dashed ci relè {3 on, 2 off). 

100-pixel diameter thin douPle-dashed circle {3 fg, 2 bg). 

10-pixel diameter circle, linewidth 1. 

100-pixel diameter circle, linewidth 10. 

500-pixel diameter circle, linewidth 50. 

100-pixel diameter dashed circle linewidth 10 (30 on, 20 off). 

100-pixel diameter douPle-dashed circle, linewidth 10 (30 fg, 20 bg). 

10-pixel diameter thin partial circle, orientation and are angle evenly di stri Puted. 

100-pixel diameter thin partial circle. 

10-pixel diameter wide partial circle. 

100-pixel diameter wide partial circle. 

I-pixel diameter filled circle. 

10-pixel diameter filled circle. 

100-pixel diameter filled circle 

500-pixel diameter filled circle. 

10-pixel diameter parti al -fi lied circle, chord fili, orientation and are angle evenly distri Puted. 
100-pixel diameter parti al-filled circle chord fili. 

10-pixel diameter parti al-filled circle, pie slice fi II, orientation and are angleevenly 
distri Puted. 

100-pixel diameter parti al-f i I led circle, pi e si i ce f i 1 1 . 

10-pixel diameter thin (linewidth 0) ellipse, major and mi noraxissizes evenly distri Puted. 

100-pixel diameter thin ellipse. 

500-pixel diameter thin ellipse. 

100-pixel diameter thin dashed ellipse (3 on, 2 off). 

100-pixel diameter thin douPle-dashed ellipse (3 fg, 2 bg). 

10-pixel diameter ellipse, linewidth 1. 
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-wellipsel 00 

-wellipse500 

-wdellipsel 00 

-wddellipse100 

-pellipse10 

-pellipse100 

-wpellipsel 0 

-wpellipse100 

-f ellipse10 

-f ellipse100 

-f ellipse500 

-f cpellipse10 

-f cpellipse100 

-f spellipse10 

-f spellipse100 

-trianglel 

-triangle10 

• triangle100 

-trapl 

-trap10 

-trap100 

-trap300 

-strapl 

-strap10 

-strapl 00 

-strap300 

-ostrapl 

-ostrap10 

-ostrap100 

-ostrap300 

-tiletrapl 

-tiletrap10 

-tiletrap100 

-tiletrap300 

-oddstrapl 

-oddstrap10 

-oddstrap100 

-oddstrap300 

-oddostrapl 

-oddostrap10 

-oddostrap100 

-oddostrap300 

-oddtiletrapl 

-oddtiletrap10 



100-pixel diameter ellipse, li ne wi dth 10. 

500-pixel diameter ellipse, li ne wi dth 50. 

100-pixel diameter dashed ellipse, linewidth 10 (30 on, 20 off). 

100-pixel diameter double-dashed ellipse, linewidth 10 (30 tg, 20 bg). 

10-pixel diameter thin partial ellipse. 

100-pixel diameter thin partial ellipse. 

10-pixel diameter wide partial ellipse. 

100-pixel diameter wide partial ellipse. 

10-pixel diameter filled ellipse. 

100-pixel diameter filled ellipse. 

500-pixel diameter filled ellipse. 

10-pixel diameter parti al -fi lied ellipse, chord fili. 

100-pixel diameter parti al-filled ellipse, chord fili. 

10-pixel diameter parti al-filled ellipse, pi e si i ce f i 1 1 . 

100-pixel diameter parti al-filled ellipse, pie sii ce f i II . 



1-pixel/side tri angle. 
10-pixel/side tri angle. 
100-pixel/side tri angle, 
lxl trapezoid. 
10x10 trapezoid. 
100x100 trapezoid. 
300x300 trapezoid. 

lxl transparent stippled trapezoid, 8x8 stipple pattern. 
10x10 transparent stippled trapezoid, 8x8 stipple pattern. 
100x100 transparent stippled trapezoid, 8x8 stipple pattern. 
300x300 transparent stippled trapezoid, 8x8 stipple pattern. 
10x10 opaque stippled trapezoid, 8x8 stipple pattern. 
10x10 opaque stippled trapezoid, 8x8 stipple pattern. 
100x100 opaque stippled trapezoid, 8x8 stipple pattern. 
300x300 opaque stippled trapezoid, 8x8 stipple pattern. 
10x10 tiled trapezoid, 4x4 tile pattern. 
10x10 tiled trapezoid, 4x4 tile pattern. 
100x100 tiled trapezoid, 4x4 tile pattern. 
300x300 tiled trapezoid, 4x4 tile pattern, 
lxl transparent stippled trapezoid, 17x15 stipple pattern. 
10x10 transparent stippled trapezoid, 17x15 stipple pattern. 
100x100 transparent stippled trapezoid, 17x15 stipple pattern. 
300x300 transparent stippled trapezoid, 17x15 stipple pattern. 
10x10 opaque stippled trapezoid, 17x15 stipple pattern. 
10x10 opaque stippled trapezoid, 17x15 stipple pattern. 
100x100 opaque stippled trapezoid, 17x15 stipple pattern. 
300x300 opaque stippled trapezoid, 17x15 stipple pat-tern. 
10x10 tiled trapezoid, 17x15 tile pattern. 
10x10 tiled trapezoid, 17x15 tile pattern. 
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-oddtiletrap100 

-oddtiletrap300 

-bigstrapl 

-bigstrap10 

-bigstrap100 

-bigstrap300 

-bigostrapl 

-bigostrap10 

-bigostrap100 

-bigostrap300 

-bigtiletrapl 

-bigtiletrap10 

-bigtiletrap100 

-bigtiletrap300 

-eschertiletrapl 

-eschertiletrap10 

-eschertiletrap100 

-eschertiletrap300 

-complex10 

-complex100 

-64poly10convex 

• 64poly1 00convex 

-64poly10complex 

-64poly100complex 

-ftext 

-f8text 

-f9text 

-f 14text16 

• tr10text 

-tr24text 

-polytext 

-polytext16 

-fitext 

-f8itext 

-f9itext 

-f 14itext16 

-f24itext16 

-tr10itext 

-tr24itext 

-SCfOll10 

-scroll100 
-scroll500 



100x100 ti I ed trapezoid, 17x15 tile pattern. 
300x300 tiled trapezoid, 17x15 tile pattern, 
lxl transparent stippled trapezoid, 161x145 stipple pattern. 
10x10 transparent stippl ed trapezoid, 161x145 stipple pattern. 
100x100 transparent stippled trapezoid, 161x145 stipple pattern. 
300x300 transparent stippled trapezoid, 161x145 stipple pattern. 
10x10 opaque stippl ed trapezoid, 161x145 stipple pattern. 
10x10 opaque stippl ed trapezoid, 161x145 stipple pattern. 
100x100 opaque stippled trapezoid, 161x145 stipple pattern. 
300x300 opaque stippled trapezoid, 161x145 stipple pattern. 
10x10 tiled trapezoid, 161x145 tile pattern. 
10x10 tiled trapezoid, 161x145 tile pattern. 
100x100 tiled trapezoid, 161x145 tile pattern. 
300x300 tiled trapezoid, 161x145 tile pattern, 
lxl tiled trapezoid, 216x208 tile pattern. 
10x10 tiled trapezoid, 216x208 tile pattern. 
100x100 tiled trapezoid, 216x208 tile pattern. 
300x300 tiled trapezoid, 216x208 tile pattern. 
10-pixel/side complex polygon. 
100-pixel/side complex polygon. 
10x10 convex 64-gon. 
100x100 convex 64-gon. 
10x10 complex 64-gon. 
100x100 complex 64-gon. 
Characterin 80-char line (6x13). 
Characterin 70-char line (8x13). 
Characterin 60-char line (9x15). 
2-byte character in 40-char Iine(kl4). 
Character in 80-char line(Times-Roman 10). 
Character in 30-char line(Times-Roman 24). 
Character in 20/40/20 li ne (6x13, Times-Roman 10, 6x13). 
2-byte character in 7/14/7 Iine(kl4, k24). 
Character in 80-char imageline(6xl3). 
Character in 70-char imageline(8xl3). 
Character in 60-char imageline(9xl5). 
2-byte character in 40-char image Iine(kl4). 
2-byte character in 23-char image line (k24). 
Character in 80-char imageline (Times-Roman 10). 
Character in 30-char imageline (Times-Roman 24). 
Serali 10x10 pixels vertically. 
Serali 100x100 pixels vertically. 
Serali 500x500 pixels vertically. 
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-copywinwin10 

-copywinwin100 

-copywinwin500 

-copypixwin10 

-copypixwin100 

-copypixwin500 

-copywinpix10 

-copywinpix100 

-copywinpix500 

-copypixpix10 

-copypixpix100 

-copypixpix500 

-copyplane10 

-copyplane100 

-copyplane500 

-putimage10 

-putimage100 

-putimage500 

-putimagexy10 

-putimagexy100 

-putimagexy500 

- shmputl 0 

-shmput100 

-shmput500 

- shmputxyl 0 

-shmputxy100 

-shmputxy500 

-getimage10 

-getimage100 

-getimage500 

-getimagexy10 

-getimagexy100 

-getimagexy500 

-noop 

-atom 

-pointer 

-prop 

-gc 

-create 

-ucreate 

-map 

-unmap 

-destroy 

-popup 



C opy 10x10 square f rom wi ndow to wi ndow. 

Copy 100x100 square from window to window. 

Copy 500x500 square from window to window. 

C opy 10x10 square from pixmap to wi ndow. 

C opy 100x100 square from pixmap to window. 

C opy 500x500 square from pixmap to window. 

Copy 10x10 square from window to pixmap. 

Copy 100x100 square from window to pixmap. 

Copy 500x500 square from window to pixmap. 

C opy 10x10 square from pixmap to pixmap. 

Copy 100x100 square from pixmap to pixmap. 

Copy 500x500 square from pixmap to pixmap. 

C opy 10x10 1-bit deep piane. 

Copy 100x100 1-bit deep piane. 

Copy 500x500 1-bit deep piane. 

Putlmage 10x10 square. 

Putlmage 100x100 square. 

Putlmage 500x500 square. 

PutlmageXY format 10x10 square 

PutlmageXY format 100x100 square. 

PutlmageXY format 500x500 square. 

Putlmage 10x10 square, M IT-shared memory extension. 

Putlmage 100x100 square, M IT-shared memory extension. 

Putlmage 500x500 square, M IT-shared memory extension. 

PutlmageXY format 10x10 square, M IT-shared memory extension. 

PutlmageXY format 100x100 square, M IT-shared memory extension. 

PutlmageXY format 500x500 square, M IT-shared memory extension. 

Getlmage 10x10 square. 

G etl mage 100x100 square. 

G etl mage 500x500 square. 

G etl mage XY format 10x10 square. 

G etl mage XY format 100x100 square. 

G etl mage XY format 500x500 square. 

X protocol NoOperation. 
GetAtomName. 
QueryPointer. 
GetProperty. 

Change graphics context. 

Create child window and map usingMapsubwindows. 

Create unmapped window. 

M ap child window viawiapwindow on parent. 

U nmap child window viaunmapwindow on parent. 

D estroy child window via Destroywindow parent. 

H i de/ expose window via M ap/U nmap pop-up window. 



xllperfcomp 
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-move 

-umove 

-movetree 

- resize 

-uresize 

-circuiate 

-ucirculate 



M ovewindow. 

M oved unmapped window. 

M ove wi ndow via Movewindow on parent. 

Resizewindow. 

Resize unmapped window. 

Circuiate lowest window to top. 

Circuiate unmapped window to top. 



XDEFAULTS 

T here are no x defaults used Py this program. 

SEEALSO 

x(l), xbench(l), x1 1 perf comp(l) 

AUTHORS 

Joel M cCormack 
Phil Karlton 
Susan AngePranndt 
ChrisKent 
Keith Packard 
GraemeGill 
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xllperfcomp 

xnperfcomp— X 11 server performance comparison program 
SYNTAX 

xllperfcomp [-rj -ro ] [ -1 label_file ] files 

D ESC RIFIO N 

The xllperfcomp program merges the output of several xnperf(l) runsinto a ni ce tabular format. 1 1 takesthe results i n 
each file, fillsin any missing test results if necessary, and for each test showstheobjects/second rateof each server. If invoked 
with the -r or - ro options, it shows the relati ve performance of each server to the first server. 

N ormally, xnperfcomp uses the first fi le speci fi ed to determi ne whi eh specific testsit should report on. Some(non-D EC:) 
serversmayfail to perform ali tests. In thiscase, xiiperfcompautomaticallysuPstitutesin a rateof 0.0 objects/second. Since 
the first fi le determi neswhich tests to report on, thi sfile must contai n asuperset of the tests reported in theother files, else 

x1 Iperfcomp will fail. 

You can provi de an explicit list of tests to report on by usi ng the -1 switch to specify a file of label s. You can create a label file 
by using the -label option in xi iperf . 

OPTIONS 

xi 1 perf comp accepts the followi ng opti ons: 

-r Specifiesthat the output should also include relative server performance, 

-ro Specifiesthat the output should include only relative server performance 

-i_iabei_fiie Specifies a label fi le to use. 
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X DEFAULTS 

There are no x defaults used by this program. 

SEEALSO 

x(l), x11perf(l) 

AUTHORS 

M ark M oraeswrote the originai scriptsto compare servers. Joel M cCormackjust munged them together a bit. 

X Versi on 11 Re!ease6 



xargs 

xargs— Build and executecommand linesfrom standard input 
SYNOPSIS 

xargs [-0prtx] [ -e[eof -str] ] [ -i[replace-str] ] [ -l[max-lines] ] [-n max-args] 
[ -s max-chars] [ -P max-procs] [--nuli] [ - -eof [=eof -str] ] [ - -replace[=replace-str] ] 
[ - -max-lines[=max-lines] ] [ - -interactive] [ - -max-chars=max-chars] [--verbose] 
[--exit] [ - -max -procs=max -procs] [ - -max-args=max-args] [ - -no-run-if -empty] 
[--version] [--help] [command [initial-arguments] ] 



D ESC RIFIO N 

Thismanual page documents the GN U version of xargs. xargs readsargumentsfrom thestandard input, delimited by 
blanks (which can beprotected with doublé or single quotes or a backslash) or newlines, and executes the command (default is 
/bm/echo) oneor more ti mes with any minai -arguments followed by arguments read from standard input. Blank lines 
on thestandard input areignored. 

xargs exitswith thefollowing status: 

0 if itsucceeds 

123 if any invocation of thecommand exited with status 1-125 

124 if thecommand exited with status 255 

125 if thecommand iskilled byasignal 

126 if thecommand cannot be run 

127 if thecommand isnotfound 

1 if some other errar occurred. 

OPTIONS 

--nuli, -0 I n put filenames are termi nated byanull character instead of by whitespace, and the quotes 

and backslash arenot special (every character istaken literally). D isablestheend-of-file 
stri ng, which istreated li ke any other argument. Useful when arguments mightcontain 
whitespace, quote marks, or backslashes. TheGN U find -printo option produces input 
suitablefor this mode. 

- - eof [=eof -str], Set the end-of-f ile stri ng to eof -str. If the end-of-file string occurs as a line of input, the 
-e [eof -str] rest of the input isignored. If eof -str is omitted, there is no end of fi le string. If this 

option isnot given, the end-of-file string defaultsto an underscore. 

- -heip Print asummary of theoptionsto xargs and exit. 

- - repiace [=r e pi a ce - st r ], Replace occurrences of r e pi a c e - s t r in the i nitial arguments with namesread from 
- 1 [r e pi a c e - s t r ] standard input. Also, unquoted blanks do not termi nate arguments. If repiace-str 

is omitted, it defaultsto {} (likefor find -exec). Implies -x and -1 1. 
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- -max -lines [=ma x ■ I i n e s ] 
- 1 [ ma x ■ I i n e s ] 

- -max-args=max- args, 
-n max - a r g s 

- -interactive, -p 

- - no - run -if -empty, -r 

- -max -chars=ma x- c ha r s , 
-s max- c ha r s 

- -verbose, -t 

- -version 

- -exit, -x 

- -max -procs=max- p r o c s , 
-P max- pr oc s 



Useat most max - 1 i nes nonblank input lines per command line; max - 1 i nes defaultsto 1 
if omitted. Trailing blanks cause an input lineto belogically continued on thenext input 
line Implies -x. 

Useat most max - args arguments per command line Fewerthan max - args argumentswill 
beused if thesize(seethe -s option) isexceeded, unlessthe -x option isgiven, in which 
casexar-gs will exit. 

Prompt the user about whether to run each command lineand read a linefrom the 
terminal. 0 nly run the command line if the response starts with y or y. Implies -t. 
If the standard input doesnot contain any nonblanks, do not run the command. N ormally, 
thecommand isrun onceeven if thereisno input. 

Useat most max - c ha r s characters per command line includi ng thecommand and initial 
arguments and the termi nati ngnuiis attheends of theargument stri ngs. The default is 
as large as possi ble, up to 20k characters. 

Print thecommand lineon the standard errar output before executing it. 
Print the version numberof xar-gs and exit. 
Exit if the size (seethe -s option) isexceeded. 

Run up tO max - procs processes at a ti me the default ÌS 1 . If max- pr oc s i S 0, xargs will 

run asmany processes as possi ble at a ti me. Use the -n option with - p; otherwise, chances 
arethat only oneexec will bedone. 



SEEALSO 

find(lL), ìocate(lL), iocatedb(5L), updatedb(l) Finding Files (online in info, or printed) 



xauth 

xauth— x authority fileutility 
SYNOPSIS 

xauth [ -f authfile ][-vqib ][command arg ... ] 

D ESC RIFIO N 

The xauth program isused to edit and display the authorization information used in connecting to thex server. This 
program isusually used to extract authorization recordsfrom onemachineand mergethem in on another (as isthecase 
when using remote logins or granting access to other users). Commands(described below) may beentered interactively, on 
the xauth command line, or in scripts. N otethat this program does not contact thex server. N ormally xauth is not used to 
create the authority file entry i n the fi rst place xdm doesthat. 

OPTIONS 

Thefollowing options may beused with xauth. They may begiven individuali (for example, -q -i ) or may combined (for 
example, -qi). 

-t authfile This option specifies the name of the authority file to use. By default, xauth will use the fi le 

specified by the xauth or ity environment variableorxauthority in theuser's home 
directory. 

-q Thisoption indicete that xauth should operate quietly and not print unsolicited status 

messages. This is the default if an xauth command isgiven on thecommand lineor if the 
standard output isnotdirected to a terminal. 

-v Thisoption indicate that xauth should operate verbosely and print status messages 

indicati ng the resultsof various operati ons(such ashow many reco rdsh ave been read in or 
written out). This isthe default if xauth isreadingcommandsfrom its standard input and 
its standard output isdirected to a terminal. 
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-i Thisoption indicate that xauth should ignore any authority fi le locks. N ormally, xauth 

will refuse to read or edit any authority fi lesthat havebeen locked by other programs 
(usually xdm or another xauth). 

-b Thisoption indicete that xauth should atterri pt to break any authority file locks before 

proceeding. Use thisoption only to clean up stale locks. 

COMMANDS 

Thefollowing commands may beused to manipulate authority files: 

add di spi ayname An authorization entry for the indicated display using thegiven protocol and key data is 

protocol name iiexkey added to the authorization file. The data is specified as an even-lengthed string of 

hexadecimal digits, each pai r representi ng one octet. T hefi rst digit of each pairgives 
the most significant 4 bits of the octet, and the second digit of the pai r givesthe least 
significant 4 bits. For example, a 32-character hexkey would represent a 128-bit value. A 
protocol name consisti ng of just a single period istreated asan abbreviation for 

MIT-MAGIC-COOKIE-1. 

[n]extract fi e n a me Authorization entri es for each of the specified displays are written to the indicated fi le. If 

di spi ayname .. . thenextract command isused, the entri es are w ri tten in a numeric format sui table for 

nonbinary transmission (such assecureelectronic mail). Theextracted entriescan beread 

back in using the merge and nmerge commands. 

If the filmarne consistsof just a single dash, the entri es will be written to the standard 
output. 

[njiist [di spi ayname .. .] Authorization entri es for each of the specified displays (or ali if no displays are named) are 
printed on the standard output. If themist command isused, entri es will beshown in the 
numeric format used by thenextract command; otherwise, they areshown in atextual 
format. Key data isalwaysdisplayed in the hexadecimal format given in the descri ption of 
the add command. 

[n]merge [f i i e n a me . . . ] Authorization entri es are read from the specified files and aremerged into the authorization 
database, superceding any matching existing entri es. If the nmerge command isused, the 
numeric format given in the descri ption of theextract command isused. If afilename 
consists of just a single dash, the standard input will beread if ithasn't been read before. 

remove di spi ayname .. . Authorization entri es matching the specified displays are rem oved from the authority file. 

source f i i e name The specified file istreated as a script contai ni ng xauth commands to execute. Blank lines 

and lines beginning with a pound sign (#) areignored. A single hyphen may beused to 
indicate thestandard input, if ithasn't al ready been read. 

info Information descri bing the authorization file, whether or not any changes havebeen made, 

and from where xauth commands are bei ng read is printed on thestandard output. 

exit If any modifications havebeen made the authority file is written out (if allowed), and the 

program exits. An end-of-fi le istreated asan implicit exit command. 

quit Theprogram exits, ignoring any modifications. This may also beaccomplished by pressing 

the interrupt character. 

heip [string] A descri ption of ali commands that begin with thegiven string (orali commands if no 

string is given) is printed on thestandard output. 
? A short list of thevalid commands is printed on thestandard output. 

DISPLAY NAMES 

Display names for the add, [njextract, [njiist, [n]merge,and remove commands use the same format as the display 
environment vari able and the common -display command-l ine argument. D isplay-specific information (such asthescreen 
number) isunnecessary and will beignored. Same-machineconnections(such aslocal-host sockets, shared memory, and the 
Internet Protocol hostnameiocaihost) arereferred to asnostname/unixidispiaynumber so that locai entries for different 



xauth 




machinesmay bestored in oneauthority file. 
EXAMPLE 

Themost common use for xauth isto extract the entry for thecurrent display, copy it to another machine, and mergeit into 
the user's authori ty fi le on the remote machi ne 

% xauth extract 
- $DISPLAY | rsh otherhost xauth merge - 

ENVIRONMENT 

Thisxauth program uses the following environment vari ables: 

xauth or ity To gei the name of the authority file to useif the -f option isn'tused. 

home Togettheuser'shomedi recto ry i f xauthor i ty i sn 't d ef i ned . 

FILES 

$HOME/.xauthority isthedefault authority file if xauthority isn'tdefined. 

X Versi on 11 Re!ease6 



[n]list [di s pi ay nane . . . ] 



[njmerge [fi I e n a me . . . ] 



remove di spi ayname . 
source f i I e ri a me 

info 
exit 
quit 

help [stringi 



Authorization entri esf or each of the specified di splays (or ali if 
no displaysarenamed) areprinted on thestandard output. If 
themist command isused, entries wi 1 1 beshown in the 
numeric format used by the nextract command; otherwise, 
they are shown in a textual format. Key data is always 
displayed in thehexadecimal format given in the descri ption of 
theadd command. 

Authorization entries are read from the specified filesand are 
merged into the authorization database, supersedingany 
matching existing entries. If thenmerge command isused, the 
numeric format given in the descri ption of theextract 
command isused. If a filmarne consistsof just a single dash, 
thestandard input will beread if it hasn'tbeen read before. 
Authorization entries matching the specified displays are 
removed from the authority file. 
The specified fi le is treated as a seri pt contai ni ng xautn 
commandsto execute. Blank linesand lines beginning with a# 
areignored. A singledash may beused to indicate the standard 
input, if it hasn't al ready been read. 
Information describi ng the authorization file, whetherornot 
any changes have been made, and from wherexautn com- 
mandsarebeing read isprinted on thestandard output. 
If any modifications have been made the authority file is 
written out (if allowed), and the program exits. An end of file 
is treated as an i mplicit exit command. 
The program exits, ignoring any modifications. This may also 
beaccomplished by pressingtheinterrupt character. 
A descri ption of ali commandsthat begin with thegiven stri ng 
(orali commandsif no stringis given) isprinted onthe 
standard output. 

i A short I ist of the vai id commandsisprinted on thestandard 

output. 

DISPLAY NAMES 

Display namesfor theadd, [njextract, [njnst, [n]merge, and remove commands use the same format astheDispuw 
environment vari able and the common -display command-lineargument. D isplay-specific information (such asthescreen 
number) isunnecessary and will beignored. Same-machineconnections(such aslocal-host sockets, shared memory, and the 
Internet Protocol nostnamei oc ai host ) arereferred to ashostname/unix:dispiaynumber so that locai entries for different 
machinesmay bestored in one authority file. 

EXAMPLE 

Themost common use for xautn isto extract the entry for the current display, copy it to another machine, and merge it into 



the user's authority fi le on the remote machi ne 



% xautn extract 
- $DISPLAY rsh otherhost xautn merge - 
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ENVIRONMENT 

Thisxauth program usesthefollowing environment variables: 

xauthority To get the name of the authority fi le to use if the -f option 

isn't used 

home To get the user's home directory if xauthority isn't defined 

FILES 

$home/. xauthority D efault authority fi le if xauthority isn't defined 

BUGS 

Usersthat haveunsecured networks should takecareto useencrypted fi le transfer mechanismsto copy authorization entries 
between machines. Similarly, theniiT-MAGic-cooKiE-1 protocol isnotvery useful in unsecured environments. Sitesthatare 
interested in additional security may need to useencrypted authorization mechanismssuch asKerberos. 

Spaces are currently not allowed in the protocol name. Quoti ng could beadded for thetruly perverse. 

AUTHOR 

Jim Fulton, M IT X Consortium 

X Versi on 11 Release6 



xbmtopbm 

xbmtopbm— Convert an Xll or X10 bitmap into a portablebitmap 



SYNOPSIS 

xbmtopbm [bit ma p f i I e ] 

D ESC RIPTIO N 

Readsan Xll orXIO bitmap as input. Produces a portablebitmap as output. 
SEEALSO 

pbmtoxbm(l), pbmtox10bm(l), pbm(5) 

AUTHOR 

Copyright (c) 1988 byjef Poskanzer. 

31 August 1988 

xcmsdb 

xcmsdb— Devi ce Color Characterization utility for X Color M anagement System 
SYNOPSIS 

xcmsdb [ -query ][-remove ] [-format 32 j 1 6 j 8 ] [f i I e n a me ] 



xclock 
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DESCRIVO N 

xcmsdb isused to load, query, or remove devi ce color characterization datastored in propertieson therootwindow of the 
screen asspecified in section 7, Device Color Characterization, of thelCCCM . Device color characterization data (al so 
called the Device Profile) isan integrai part of Xlib'sX Color M anagement System (xcms), necessary for proper conversion 
of color specification between device-independent and device-dependent forms. xcms uses3x3 matricesstored in the 
xdccc_li near_rgb_matr i ces property to convert color specificati ons between CIEXYZ and RGB Intensi ty (XcmsRGBi, also 
referred to as linear RGB), xcms then uses display gamma information stored in the xdccc_linear_rgb_correction property to 
convert color specifications between RGBi and RGB device (Xcm sRGB, also referred to as device RGB). 

N otethat xcms allowsclientsto register function setsin addition to itsbuilt-in function set for CRT color monitors. 
Additional function sets may storetheir devi ce profile information in other properties in function set specific format. This 
utility isunawareof these nonstandard properties. 

T he ASC 1 1 readablecontentsof filename (or the standard input if no input file isgiven) areappropriately transformed for 
Storage in properties, provided the -query or -remove optionsare not specified. 

OPTIONS 

xcmsdb program acceptsthefollowing options: 

-query T his option attempts to read theX D C C C properties off the 

screen's rootwindow. If successful, it transforms the data into 
a more readable format, then sends the data to standard out. 

-remove T his option attempts to remove the X D C C C propertieson the 

screen's rootwindow. 

-format 32ji6j8 Specifies the property format (32, 16, or 8 bits per entry) for 

the xdccc_linear_rgb_correction property. Preci sion of 
encoded floating-point valuesincreaseswith theincreasein 
bits per entry. The default is 32 bits per entry. 

SEE ALSO 

xprop(l), Xlib documentation 

ENVIRONMENT 

display To figure out which display and screen to use 



AUTHOR 

Chuck Adams, Tektronix, Inc., and Al Tabayoyon, SynChromatics, Inc. (added multi visual support) 
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xciock— Analog/digi tal clock forX 
SYNOPSIS 

xclock [ -help ][-analog ] [-digitai ][-chime ][-hd coi or ][-hl color ] 
[-update seconds ][-padding n u mbe r ] 

DESCRIPTION 

The xciock program displaysthetimein analog or digitai form. The ti mei sconti nuously updated at afrequency which may 
be specified by the user. 
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OPTIONS 

xciock accepts ali of the standard X Tool kit command-l ine options along with theadditional options listed here: 



-help 



-analog 



-digitai Or -d 



-chime 



-hands color (or -hd color) 



-highlight color (or -hi color) 



-update seconds 



-padding number 



Thisoption indicete that a brief summary of theallowed 
options should beprinted on the standard error. 
Thisoption indicate that a conventional 12-hour clock face 
with tick marksand hands should beused. Thisisthe default. 
Thisoption indicate that a 24-hour digitai clock should be 
used. 

Thisoption indicate that the clock should chimeonceon the 
half hour and twice on the hour. 
Thisoption specifies the color of thehandson an analog 
clock. The default isbiack. 

Thisoption specifies the color of theedges of thehandson an 
analog clock, and isonlyuseful on color displays. The default 
iSblack. 

Thisoption specifies thefrequency in seconds atwhich xciock 
should update its display. If the clock isobscured andthen 
exposed, itwill beupdated immediately. A valueof 30 seconds 
or lesswill enablea second hand on an analog clock. The 
default ÌS60 seconds. 

Thisoption specifies the width in pixels of the padding 
between thewindow border and clock text or picture The 
default i s 1 0 on a digitai clock and 8 on an analog clock. 



XDEFAULTS 

Thisprogram usestheClockwidget. It understandsall of thecoreresourcenamesand classesaswell as: 

width (class Width) 



height (class Height) 

update (class Interval) 
foreground (class Foreground) 

hands (class Foreground) 

highlight (class Foreground) 

analog (class Boolean) 
chime (class Boolean) 



Specifi es the wi dth of the clock. The default for analog clocks 
is 1 64 pixels; the default for digitai clocks iswhatever isneeded 
to hold the clock when displayed inthechosen font. 
Specifies the height of the clock. The default for analog clocks 
is 1 64 pixels; the default for digitai clocks iswhatever is needed 
to hold the clock when displayed inthechosen font. 
Specifies thefrequency in seconds atwhich thetimeshould be 
redi splay ed. 

Specifies the colorforthetick marks. The default isdepends 
on whether reverseVideo is specifi ed. If reverseVideo is 
specifi ed, thedefault isiwhite; otherwise, the default isbiack. 
Specifies the color of the insides of the clock's hands. T he 
default dependson whether reverseVideo is specifi ed. If 
reverseVideo is specified, thedefault isiwhite; otherwise, the 
default isbiack. 

Specifies the color used to highlight the clock's hands. The 
default dependson whether reverseVideo is specified. If 
reverseVideo isspecified, the default is ìwhite; otherwise, the 
default isbiack. 

Specifies whether or not an analog clock should beused 
instead of a digitai one. Thedefault isTrue. 
Specifies whether or not a beli should berungon the hour and 
half hour. 



padding (class Margin) 
font (class Font) 



xcli pboard 




Specifies the amount of internai padding in pixelsto beused. 
The default iss. 

Specifies the font to beused forthedigital clock. N otethat 
variable width fontscurrently will not always display correctly. 



WIDGETS 

In order to specify resources, it isuseful to know thehierarchy of thewidgetswhich compose xciock. In thefollowing 
notation, indentation indicates hierarchical structure. The widget class nameisgiven first, followed by thewidget instance 
name 

XClock xciock 
Clock clock 

ENVIRONMENT 

display To get thedefault host and display number 

xenvironment To get the name of a resource fi le that overri des the global 

resources sto red in the resource jianager property 

FILES 

<xRoott/iib/xn/app-defauits/xciock Specifies required resources 

SEE ALSO 

x(l), xrdb(l), time(3C) 

BUGS 

xciock bel ieves the system clock. 

When in digitai mode, thestring should becentered automati cally. 
AUTHORS 

Tony Della Fera(M IT-Athena, DEC), DaveM ankins(M IT-Athena, BBN), and Ed M oy (UC Berkeley) 

X Versi on 11 Re!ease6 

xclipboard 

xciipboard— X clipboard client 
SYNOPSIS 

xclipboard [ -toolkitoption ... ] [ -w ][-nw ] 

D ESC RIFTIO N 

The xclipboard program isused to collect and display text selectionsthat aresentto the Clipboard by other clients. It is 
typically used to save Clipboard selectionsfor later use. It storeseach Clipboard selection as a separate stri ng, each of which 
can beselected. Each time Clipboard isasserted by another application, xclipboard transfers the contentsof that selection to 
anew buffer and displaysit in the text window. Buffersarenever automatically deleted, so you'll wantto use the delete 
butto n to get rid of useless items. 

Since xclipboard uses a Text W idget to display the contentsof the clipboard, textsentto the Clipboard may bereselected for 
use in other applicati ons. xclipboard also respondsto requestsfor the Clipboard selection from other clients by sending the 
enti re contents of the currently displayed buffer. 
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An xciipboard window hasthefollowing buttonsacrossthetop: 

quit When this button ispressed, xciipboard exits. 

delete When this button ispressed, thecurrent buffer isdeleted and 

the nextone display ed. 

new C reatesa new buffer with no contents. U seful in constructing 

a new C lipboard selection by hand. 

save D isplaysa FileSavedialog box. Pressing the A ccept button 

savesthecurrently displayed buffer to the fi le specified in the 
textfield. 

next D isplaysthenext buffer in the list, 

previous D isplays the previous buffer. 

OPTIONS 

Thexciipboard program acceptsall of the standard X Tool kit command-lineoptionsaswell as the following: 

-w Thisoption indicates that lines of text that are too longto be 

displayed on onelinein theclipboard should wrap around to 
thefollowing lines. 

-nw Thisoption indicates that long lines of text should notwrap 

around. T his isthe default behavior. 

WIDGETS 

In order to specify resources, it isuseful to know the hierarchy of thewidgetswhich compose xciipboard. In thefollowing 
notation, indentation indicates hi erarchi cai structure. The widget class nameisgiven first, followed by thewidget instance 
name. 

XClipboard xclipboard 
Form forni 

Command Quit 

Command delete 

Command new 

Command Save 

Command next 

Command prev 

Label index 

Text text 
TransientShell f ileDialogShell 

Dialog fileDialog 

Label label 

Command accept 

Command cancel 

Text value 
TransientShell f ailDialogShell 

Dialog failDialog 

Label label 

Command continue 

SEN D I N G / RETRI EVI N G C LIPBOARD CONTENTS 

Text iscopied to the C lipboard whenever a client asserts ownership of the C lipboard selection. Text iscopied from the 
C lipboard whenever a client requests the contents of the C lipboard selection. Examplesof event bindingsthat a user may 
wish to includein a resourceconfiguration fileto use the C lipboard are 



*VT100.Translations: #override \ 
<Btn3Up>: select-end(CLIPBOARD) \n\ 
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<Btn2Up>: insert-selection(PRIMARY,CLIPBOARD) \n\ 
<Btn2Down>: ignore () 

SEEALSO 

x(l), xcutsei(l), xterm(l), individuai client documentation for how to makeaselection and send itto theClipboard. 
ENVIRONMENT 

display To get thedefault host and display number 

xenvironment To get the name of a resource fi le that overri des the global 

resourcesstored in the resource janager property 

FILES 

<xRoot>/iib/xn/app-defauits/xciipboard Specifies required resources 

AUTHOR 

Ralph R. Swick(D EC/M IT Project Athena), ChrisD . Peterson (M IT X Consortium), Keith Packard (M IT X Consortium) 

X Versi on 11 Re!ease6 



xconsole 



xconsole— M onitor system console messages with X 
SYNOPSIS 

xconsole [ -tool ki t opti on ...] [-file file- name] [-notify] [ -stripNonprint] [-daemon] [-verbose] 
[ -exitOnFail] 

DESCRIVO N 

Thexconsoie program displays messages that are usually sent to /dev/consoie. 



OPTIONS 

xconsole acceptsall of the standard X Tool kit command- 

-file f I I e- name 
-notify, -nonotify 

-daemon 

-verbose 

-exitOnFail 



ne options along with theadditional options listed here 

To monitor someother device, usethisoption to specify the 
device name. T hi sdoesnotwork on regular fi les as they are 
always ready to be read from. 

When new data arereceived from the console and the notify 
option is set, theicon name of the application has* appended, 
so that it isevident even when the application isiconified. - 
notify isthe default. 

Thisoption causes xconsole to place itself in the background, 

USing fork/exit. 

When set, thisoption di rects xconsole to display an informa- 
ti ve m essage in th e f i rst I i n e of th e text buffer. 
When set, thisoption di rects xconsole to exit when it isunable 
to redi rect the console output. 



XDEFAULTS 

This program uses the Athena Text widget, look in the Athena W idget Set documentation for control li ng it. 
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WIDGETS 

In order to specify resources, it isuseful to know the hierarchy of the widgets that compose xconsoie. In thefollowing 
notation, indentation indicates hierarchical structure. The widget class nameisgiven first, followed by thewidget instance 
name 

XConsole xconsoie 
XConsole text 

ENVIRONMENT 

DISPLAY 
XENVIRONMENT 



To get the default host and display number. 
T o get th e n am e of a resou ree f i I e th at o verri des th e gl o bai 
resources sto red in the resource_manager property. 



FILES 

<XRoot>/lib/X11/app-defaults/XConsole 

SEEALSO 

x(l), xrdb(l), AthenaTextwidget 

AUTHOR 

Keith Packard (M IT X Consortium) 



Specifies required resources 



X Versi on 11 Re!ease6 



xcutsel 

xcutsei— Interchange between cut buffer and selection 
SYNOPSIS 

xcutsel [ -tooì ki topti ori ...] [ -selection s el ect i on ] [ -cutbuffer number ] 

D ESC RIPTIO N 

The xcutsei program isused to copy the current selection into a cut buffer and to make a selection that contai ns the current 
contents of the cut buffer. It acts as a bridge between applications that don't support selections and those that do. 

By default, xcutsei will use the selection named primary and the cut buffer cut_buffer0. Either or both of thesecan be 
overridden by command-lineargumentsorby resources 

An xcutsei window has thefollowing buttons 

quit 



copy PRIMARY to 0 



copy 0 to PRIMARY 



When thisbutton ispressed, xcutsei exits. Any selections held 
by xcutsei are automati cai ly released. 
When thisbutton ispressed, xcutsei copi es the current 
selection into the cut buffer. 

When thisbutton ispressed, xcutsei converts the current 
contents of the cut buffer i nto the selection. 



Thebutton labels reflect the selection and cut buffer selected by command-lineoptionsor through the resource database. 

When the copy 0 to PRIMARY button isactivated, thebutton will remai n inverted as long as xcutsei remai ns the owner of 
theselection. Thisservesto remind you which clientowns the current selection. N ote that thevalueof the selection remains 
Constant; if the cut buffer ischanged, you must again adivate the copy button to retri ève the new valuewhen desi red. 
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OPTIONS 

xcutsei acceptsall of the standard X Toolkitcommand-lineoptionsaswell asthefollowing: 

-seiection nane This option specifies the name of the seìection to use The 

default ìsprimary. Theonly supported abbrevi ationsfor this 
option are -seiect, -sei, and -s, asthe standard toolkit option 
-seiectionTimeout hasa similar name. 

-cutbuffer n umber T his option specifies the cut buffer to use. T he default is 

cutbuffer 0. 

XDEFAULTS 

Thisprogram acceptsall of the standard X Toolkit resourcenamesand classesaswell asthefollowing: 

seiection (class seiection) This resource specifies the name of the seiection to use. The 

default ìsprimary. 

cutBuffer (class cutBuffer) This resource specifies the number of the cutbuffer to use. 

The default i s 0. 

WIDGETNAMES 

The followi ng instancenames may beused when user configuration of thelabels in them isdesired: 

sel-cut (class Command) This ÌS the "COpy SELECTION tO BUFFER" button. 

cut-sel (class Command) T his ÌS the "COpy BUFFER tO SELECTION" button. 

quit (class Command) T his ÌS the "quit" button. 

SEEALSO 

x(l), xciipboard(l), xterm(l), text widget documentation, individuai client documentation for how to make a seiection. 
BUGS 

There is no way to change the nameof the seiection or the number of the cut buffer while the program is running. 
AUTHOR 

Ralph R. Swick(D EC/M IT Project Athena) 

X Versi on 11 Re!ease6 

xdm 

xdm— X D isplay M anagerwith support forXD M CP, hostcnooser 
SYNOPSIS 

xdm [ -config confi gurati on_fi I e ][-nodaemon ][-debug debugi evel ] 
[-error er r or_t og_f i I e ] [-resources resource_fi I e ][-server server_entry ] 
[-sessi onsessi on_program] 

DESCRIPTION 

xdm managesacollection of X displays, which may beon the locai hostor remote servers. The design of xdm wasguided by 
theneedsof X terminalsaswell astheX Consorti um standard xdmcp, theX D isplay M anager Control Protocol, xdm provides 
servi ces si milarto thoseprovided by init, getty, and ìogin on character termi nals: promptingfor login name and password, 
authenticating the user, and running a session. 
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A session isdefined by the lifetime of a particular process; in thetraditional character-based terminal world, it is the user's 
login shell. In thexdm context, it isan arbitrary session manager. T hi s isbecausein a windowingenvironment, a user's login 
shell process does not necessari ly haveany termi nal-like interface with which to connect. When a real session manager isnot 
available, a window manager or terminal emulator istypically used as the session manager, meaningthat termi nation of this 
process termi nates the user's session. 

When thesession isterminated, xdm resetstheX server and (optionally) restarts the whole process. 

When xdm receivesan Indirect query viaXD M CP, itcan run a chooser process to perform an XD M CP BroadcastQuery (or 
an XD M CP Query to specified hosts) on behalf of the display and offer a menu of possible hosts that offer XDM CP display 
management. Thisfeatu re isuseful with X terminalsthat do not offer a host menu themselves. 

Becausexdm provides the first interface that userswi II see, it isdesigned to besimpleto use and easy to customizeto theneeds 
of a particular site, xdm hasmanyoptions, mostof which havereasonabledefaults. Browsethrough thevarioussectionsof this 
manual, picking and choosingthethingsyou want to change. Pay particular attention to the "Session Program" subsection, 
which wi II describehow to set up the styleof session desi red. 

OVERVIEW 

xdm ishighly configurable, and mostof its behavior can be controlied by resource files and shell seri pts. The namesof these 
fi les themselves are resources read from thefilexdm-config orthefilenamed bythe-config option. 

xdm offers di splay management two differentways. Itcan manageX servers runningon the locai machine and specified in 
xservers, and it can manageremoteX servers (typically X terminals) using xdmcp (theXD M Control Protocol) as specified in 
thexaccess file. 

T he resources of the X clients run by xdm outside the user's session, includi ngxdm'sown login window, can beaffected by 
setting resources in thexresources file. 

ForX terminalsthat do not offer a menu of hosts to get display management from, xdm can col lect willing hosts and run the 
chooser program to offer the user a menu. ForX displays attached to a host, this step istypically not used, as the locai host 
does the display management. 

After resetting theX server, xdm runsthexsetup script to assist in setting up thescreen the user sees along with thexiogin 
widget. 

When the user logs in, xdm runsthexstartup script asroot. 

Then xdm runsthexsession script as the user. This system session filemay do some additional startup and typically runsa 
script in the user's home directory. When thexsession script exits, thesession isover. 

At the end of thesession, thexreset script isrun to clean up, theX server is reset, and the cycle starts over. 

The fi le /usr/xiiR6/iit>/xn/xdm/xdm-errors will contain errar messages from xdm and anything output to stderr by xsetup, 
xstartup, xsession, or xreset. When you have trouble getti ng xdm working, check this fi le to see if xdm hasany cluesto the 
trouble. 

OPTIONS 

Ali of these opti ons, except -config itself, specify vai ues that can also be specified in theconfiguration fi le as resources. 



-conf ig confi gurati on_fi I e 



-nodaemon 



N ames theconfiguration file, which specifies resources to 

Control the behavior Of xdm. <XRoot>/lib/X11/xdm/xdm-config is 

the default. See the subsection called "Confi gurati on File." 

Specifi es false as the value for the DisplayManager . daemonMode 

resource. This suppresses the normal daemon behavior, which 
isfor xdm to dose ali file descri ptors, di sassociate itself from the 
controlli ng terminal, and put itself in the background when it 
first starts up. 



xdm 



-debug debug! ève 



-error error i o g _ f i I e 



-resources r esour ce file 



-server ser«er_entry 



-udpPort p o r t _ n u mb e r 



-session sessi o n _ p r ogr a m 



-xrm r es our ce_s pec i f i cat i ori 



Specifies the numeric valuefor theDisplayManager.debugLevel 

resource. A non-zero value causes xdm to print lotsof 
debugging statementsto the terminal; it also disablesthe 

DisplayManager.daemonModeresource, forcing xdm tO run 

synchronously. To interpret these debugging messages, a copy 
of the source code for xdm isalmost a necessity. N o atterri pt has 
been madeto rationalizeor standardize the output. 

Specifiesthevaluefor theDisplayManager.errorLogFile 

resource. This file contai nserrorsfrom xdm aswell asanything 
written to stderr by the vari ous seri pts and programsrun 
during the progress of the session. 

Specifies the valuefor the DispiayManager*resources resource 
Thisfileisloaded usingxrdb to specify configuration 
parametersfortheauthentication widget. 
Specifiesthevaluefor theDispiayinanager.servers resource. 
Seethesubsection "Locai Server Specification" for a descrip- 
tion of this resource. 

Specifi es the value for the DisplayManager . requestPort 

resource. This sets the port number, which xdm will monitor 
forXDM CP requests. AsXD M CP uses the regi stered well- 
known U D P port 177, this resource should not bechanged 
except for debugging. 

Specifiesthevaluefor theDispiayinanager*session resource. 
This indicates the program to run as the session after theuser 
haslogged in. 

Allowsan arbitrary resource to bespecified, asin mostX 
Toolkit applications. 



RESOURCES 

At many stagestheactionsof xdm can be controlied through the use of its configuration file, which is in theX resource 
format. Some resources modify the behaviorof xdm on ali displays, while others modify its behavior on a single display. 
Whereactions relate to a specific display, the display nameis inserted into the resource name between Display -Manager and 
the final resource name segment. 

For locai displays, the resource name and class areas read from thexservers file. 

For remote displays, the resource name iswhat the network addressof the di splay resolvesto. SeetheremoveDomain resource. 
The name must match exactly; xdm isnot awareof ali the network aliases that might reach agiven display. If the name resolve 
fails, the addressisused. The resource class isassent by the display in theXD M C P M anage request. 

Becausethe resource manager usescolonsto separate the name of the resource from its value and dotsto separate resource 
nameparts, xdm substitutesunderscoresfor both dotsand colonswhen generati ng the resource name. Forexample, 
DisplayManager. expo x org o.startup is the name of the resource that defi nes the startup shell filefortheexpo.x.orgio 
display. 

DisplayManager. servers This resource either specifies a filename full of server entries, 

oneper line (if the value starts with aslash), or a single server 
entry. Seethesubsection "Locai Server Specification" for the 
detai Is. 

DisplayManager. requestPort This indicates the U D P port number that xdm usesto li sten for 

incomingXD M CP requests. U nlessyou need to debug the 
system, leavethiswith its default value of 177. 



] 
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DisplayManager.errorLogFile 



DisplayManage r.debugLevel 



DisplayManage r . daemonMode 



DisplayManage r.pidFile 

DisplayManager.lockPidFile 

DisplayManage r.authDir 
DisplayManage r.autoRescan 

DisplayManager . removeDomainname 



DisplayManage r.key File 



E rror output isnormally directed at the system console. To 
redirect it, set th is reso u ree to afilename. A method to send 
thesemessagesto sysiog should bedeveloped for systemsthat 
support it; however, the wide vari ety of interfaces precludes 
any system-independent implementation. Thisfilealso 
contai nsany output directed to stderr by thexsetup, xstartup, 
xsession, and xreset files, so itwill contain descriptionsof 
problemsin those scriptsaswell. 
If the integer value of this resource is greater than zero, reams 
of debugging information will beprinted. It also disables 
daemon mode, which would redirect the information into the 
bit-bucket, and allowsnonroot usersto run xdm, which would 
normally not beuseful. 

N ormally, xdm attemptsto makeitself into a daemon process 
unassociated with anyterminal. Thisisaccomplished by 
forking and leaving theparent process to exit, then closingfile 
descriptorsand releasing the controlling terminal. In some 
environmentsthisisnotdesired (in parti cular, when 
debugging). Setti ng this resource to false will disablethis 
feature. 

Thefilenamespecified will becreated to contain an ASCII 
representation of the process-id of themain xdm process. xdm 
also usesfilelocking on this fi le to attempt to eliminate 
multi pie daemonsrunning on the same machine, which would 
causequiteabitof havoc. 

Thisis the resource which controlswhether xdm usesfile 
lockingto keep multiple display managersfrom running 
amok. On System V, thisusestheiockf library cali, whileon 
BSD itusesfiock. 

Thisnames a directory in which xdm sto res auth o ri zati o n files 
whileinitializing the session. The default value isy. 
ThisBoolean controlswhether xdm rescans the confi guration, 
servers, access control and authentication keys fi les after a 
session terminatesand the files havechanged. By default it is 
true. You can forcexdm to reread these files by sending a 
sighup to themain process. 

When computing the display nameforxDMCP clients, thename 
resolver will typically create a fui ly qual if i ed hostnameforthe 
terminal. As this is sometimes confusing, xdm will remove the 
domain name porti on of the hostname if it is the same as the 
domain name of the locai hostwhen this variableis set. By 
default the value istrue. 

xdm -authentication -1 styleXD M CP authenti cati on requires 
that a private key beshared between xdm and the terminal. This 
resource specifies the fi le contai ni ng those values. Each entry 
in thefile consists of a display nameand theshared key. By 
default, xdmdoesnot include support for xdm-authentication-1, 
asit requires des, which isnot generally distributable because 
of U nited States export restrictions. 



DisplayManager.accessFile 

DisplayManager. export List 
DisplayManager.randomFile 
DisplayManager. greeterLib 
DisplayManager. choiceTimeout 

DisplayManager. DI SPLAY .resources 



DisplayManager. DI SPLAY .chooser 

DisplayManager. DI SPLAY .xrdb 
DisplayManager. DI SPLAY .cpp 
DisplayManager. DI SPLAY .setup 

DisplayManager. DI SPLAY .startup 
DisplayManager. DI SPLAY .session 



Xdm ^ 

To prevent unauthorized XD M CP serviceand to allow 
forwarding of XDM CP mdirectQuery requests, this fi le 
contai ns a database of hostnames that are either allowed direct 
access to thismachine, or havea list of hoststo which queries 
should beforwarded to. Theformatof thisfileisdescribed in 
thesubsection "XD M CP Access Control." 
A listof additional environment variables, separated by 
whitespace, to passon to thexsetup, xstartup, xsession.and 
xreset programs 

A fileto checksum to generate the seed of authorization keys. 
This should be a file that changes frequently. T he default is 

/dev/mem. 

On systems that su pport a dynamically loadable greeter library, 
the nameof the library. Default is<XRoot>/iib/xn/xdm/ 

libXdmGreet . so. 

N umber of secondsto waitfor display to respond after user 
hasselected ahostfrom thechooser. If the di splay sendsan 
XD M CP mdirectQuery within thistime, therequest is 
forwarded to thechosen host. Otherwise, it isassumed to be 
from a new session and thechooser isoffered again. Default 

ÌS15. 

Thisresource speci fi es the nameof the fileto beloaded by 
xrdb as the resource database onto the rootwindow of screen 0 
of thedisplay. Thexsetup program, the Login widget, and 
chooser wi 1 1 use the resources set i n this fi le. T hi s resource 
database is loaded just before the authentication procedure is 
started, so it can control the appearanceof the login window. 
See thesubsection "Authentication Widget," which describes 
th e vari ous resources th at are appro pri ate to pi ace i n th i s f i I e. 
Thereisno default valuefor thisresource, but <xRoot>/iib/ 
xn /xdm/xresources istheconventional name. 
Specifies the program run to offer a host menu for mdirect 
queries redirected to the special hostname chooser. <xRoot> 
/iib/xn/xdm/chooser is the default. See the subsections 
"XD M CP Access Control" and "chooser." 
Specifies the program used to load theresources. By default, 

xdm USeS <XRoot>/bin/xrdb. 

T his specifies the nameof the C preprocessor that isused by 

xrdb. 

This specifies a program thatisrun (asroot) before offerì ng 
the Login window. Thismay beused to changetheappearance 
of the screen around the Login window orto put up other 
Windows (for exam pie, you may wantto run xconsoie here). 
By default, no program isrun. The conventi onal name fora 
fileused hereisxsetup. See thesubsection "Setup Program." 
This specifies a program that is run (as root) after the 
authentication process succeeds. By default, no program isrun. 
Theconventional nameforafileused hereisxstartup. See the 
subsection "Startup Program." 

This specifies the session to beexecuted (not runningas root). 
By default, <xRoot>/bin/xterm isrun. Theconventional name 
isxsession. Seethesubsection "Session Program." 
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DisplayManager.DI SPLAY .reset 



DisplayManager.DI SPLAY .openDelay, 
DisplayManager.DI SPLAY .openRepeat, 
DisplayManager.DI SPLAY . openTimeout, 
DisplayManager.DI SPLAY . startAttempts 



DisplayManager.DI SPLAY . pinglnterval, 
DisplayManager.DI SPLAY. pingTimeout 



DisplayManager.DI SPLAY . 
terminateServer 



DisplayManager.DI SPLAY .userPath 



DisplayManager.DI SPLAY . 
systemPath 



T his specifies a program which isrun (asroot) after thesession 
terminate. Again, by default, no program isrun. The 
conventional nameisxreset. Seethesubsection "Reset 
Program." 

Thesenumeric resources control thebehaviorof xdm when 
attemptingto open intransigentservers. openDelay isthelength 
of thepause(in seconds) between successive attempts, 

openRepeat isthe number Of attempts tO make openTimeout is 

the amount of ti me to wait while actually attempting the open 
(that is, the maximum timespent in theconnect(2) system 
cali) and startAttempts isthenumber of timesthisentire 
process isdone before giving up on the server. After openRepeat 
attempts h ave been made, or if openTimeout seconds elapse in 
any parti cu I ar atterri pt, xdm terni inates and restarts the server, 
attemptingto connect again. T his process is repeated 
startAttempts ti mes, atwhich point thedisplay is declared 
dead and disabled. Although this behavior may seem arbitrary, 
ithasbeen empirically developed and worksquitewell on 
most systems. The default values are 5 for openDelay, 5 for 

openRepeat, 30 for openTimeout and 4 for startAttempts. 

To discover when remote displaysdisappear, xdm 
occasionali pingsthem, usi ng an X connection and xsync 
calla pingmtervai specif i es the ti me ( i n minutes) between 
each pingattempt, pingTimeout specifies the maximum 
amount ottime (in minutes) to wait for the terminal to 
respond to therequest. If theterminal does not respond, the 
session is declared dead and termi nated. By default, both are 
set to 5 minutes. If you frequently useX terminalsthat can 
becomeisolated from the managing host, you mightwantto 
i ncrease this vai ue. The onlyworry isthat sessionswill 
conti nueto exist after the terminal hasbeen accidentali 
disabled. xdmwill not ping locai displays. Although itwould 
seem harmless, it isunpleasantwhen the workstation session is 
termi nated asa result of the server hangingfor N FS servi ce 
and not respondingto the ping. 

ThisBoolean resource specifies whether the X server should be 
terminated when a session terminates (instead of resetting it). 
Thisoption can beused when the server tendsto grow 
without bound over ti me, in order to li mit the amount ottime 
theserver isrun. The default value istaise. 
xdm setsthePATH environment vari ablefor the session to this 
value. It should bea colon separated list of di recto ri es; see 

sh(l) forafull descri ption. :/bin:/usr/bin:/usr/X11R6/bin 

:/usr/ucb isacommon setti ng. The default value can be 
specified at build timein thex system configuration filewith 

DefaultUserPath. 

xdm setsthePATH environment vari ablefor the startup and reset 
scripts to the value of this resource. T he default for this 
resource is specified at build timeby theDefauitsystem-Patn 
entry in the system configuration file; /etc:/bin:/usr/bin 



xdm 



DisplayManager.DI SPLAY. 
systemShell 

DisplayManager.DI SPLAY 
failsafeClient 



DisplayManager.DI SPLAY .grabServer, 
DisplayManager.DI SPLAY. grabTimeout xdm 



DisplayManager.DI SPLAY .authorize, 
DisplayManager.DI SPLAY .authName 



DisplayManager.DI SPLAY .authFile 



DisplayManager.DI SPLAY . 
authComplain 

DisplayManager.DI SPLAY. 
resetSignal 

DisplayManager.DI SPLAY. 
termSignal 



: /usr/xnR6/bin:/usr/ ucb isacommon choice. Note the 
absenceof (.) from this entry. This isagood practiceto follow 
forroot; itavoidsmany common Trojan H orse system 
penetration schemes. 

xdm setsthesHELL environmentvariableforthestartup and 
reset seri ptsto the valueof this resource ltis/bin/sh by 

default. 

If the default session failsto execute, xdmwill fall back to this 
program. This program isexecuted with no arguments, but 
executes u si ng t h e sam e en vi ro n m ent vari abl es as th e sessi o n 
would havehad. (Seethesubsection "Session Program.") By 
default, <xRoot>/bin/xterm isused. 
To improve security, this grabs the server and keyboard while 
readingthelogin nameand password. The grabServer resource 
specifiesif the server should beheld for the durati on ofthe 
name/ password reading. When false, the server isungrabbed 
after the keyboard grab succeeds; otherwise, the server is 
grabbed until just before the session begins. The default is 
false. T he grabTimeout resource specifies the maxi mum time 
xdm wi 1 1 wait for the grab to succeed. The grab mayfail if some 
other client hastheserver grabbed, or possibly if thenetwork 
I atenei es are very high. This resource has a default value of 3 
seconds; you should be cauti ous when rai si ng it, asa user can 
bespoofed by a look-ali kewindow on the display. If the grab 
fails, xdm killsand restarts the server (if possi ble) and the 
session. 

authorize isaBoolean resource that controis whether xdm 
generates and uses authorization for the locai server connec- 
tions. If authorization isused, authName is a list of authorization 
mechanismsto use, separated by whitespace. XD M C P 
connectionsdynamically speci fywhich authorization 
mechanismsaresupported, so authName isignored inthiscase. 
When authorize isset for a display and authorization isnot 
available, theuser isinformed by having a different message 
displayed in the Login widget. By default, authorize istrue. 

authName ÌSMIT-MAGIC-COOKIE-1, Ol", if XDM -AUTHORIZATION -1 ÌS 

available, xdm -authorization -1 mit-magic-cookie-1 . 
Thisfileisused to communicatetheauthorization data from 

xdm tO the Server, USingthe-auth server command-line Option. 

It should be kept in a directory that is not world-writable as it 
could easily be removed, disabling the authorization mecha- 
nism in theserver. 

If setto false, disablestheuseof theunsecureGreeting in the 

login window. Seethesubsection "Authentication W idget." 
Thedefault istrue. 

Thenumberof the signal xdm sendsto reset the server. 
Seethesubsection "Controlling the Server." Thedefault isi 
(sighup). 

Thenumberof the signal xdm sendsto termi nate the server. See 
thesubsection "Controlling theServer." Thedefault is 15 
(sigterm). 
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DisplayManager.DI SPLAY 
userAuthDir 



DisplayManager.DI SPLAY 
resetForAuth 



Theoriginal implementation of authorization in thesample 
server reread theauthorization fileat server reset time, instead 
ofwhen checking the initi al connection. Asxdm generatesthe 
authorization information just beforeconnecting to the 
display, an old server would not get up-to-date authorization 
information. Thisresource causes xdm to send sighup to the 
server after setti ngupthefile, causi ngan additional server reset 
tooccur, duringwhich ti methenew authorization information 
will beread. The default is false, which will work for ali M IT 
servers. 

When xdm isunableto writeto theusual user authorization file 
($home/ .xauthority), it createsa uniquefilename in this 
directory and pointstheenvironment variablexAUTHORiTY at 
thecreated file. It uses /tmp by default. 



CO NFIGU RATIO N FILE 



First, the xdm configuration file should beset up. M ake a directory (usually <xRoot>/iib/xn/xdm, where <XRoot>refersto the 
root of the X 11 instali tree) to contai n ali of therelevant files. In theexamplesthatfollow, /usr/xnR6 isused asthevalueof 



H ere is a reasonable configuration file, which could benamed xdm-config: 

DisplayManager. servers: /usr/X1 1R6/lib/X1 1 /xdm/Xservers 
DisplayManager.errorLogFile: /usr/X1 1R6/lib/X1 1 /xdm/xdm-errors 
DisplayManager*resources: /usr/X1 1 R6/lib/X1 1 /xdm/Xresources 
DisplayManager*startup: /usr/X1 1R6/lib/X1 1 /xdm/Xstartup 
DisplayManager*session: /usr/X1 1R6/lib/X1 1 /xdm/Xsession 
DisplayManager. pidFile: / usr/X1 1R6/lib/X1 1 /xdm/xdm-pid 
DisplayManager. O.authorize: true 
DisplayManager*authorize: false 

N otethat this file mostly contai nsreferencesto other files. N otealso that some of the resources are specified with * 
separati ng the components. These resources can bemadeuniqueforeach different display, by replacing the* with the 
display name, but normally this is not very useful. See the "Resources" section for a complete discussion. 



The database fi le specified by theDispiayManager.accessFiie provides information which xdm usesto control access from 
displays requesti ng XD M CP service. This fi le contai nsthreetypesof entries: entri es that control theresponseto Direct and 
Broadcast queries, entries that control theresponseto mdirect queries, and macro defi nitions 

T he format of the Direct entries issimple, either a hostnameor a pattern, which is disti nguished from a hostname by the 
inclusi on of oneor moremetacharacters(* matchesany sequenceof 0 ormorecharacters, and? matchesany single 
character) which arecompared against the hostname of the display device. If the entry is a hostname, ali co m pari so ns are 
doneusing network addresses, so any name which convertsto thecorrect network addressmay beused. For patterns, only 
canoni cai hostnamesareused in thecomparison, so ensurethat you do not attempt to match aliases. P recedi ng either a 
hostname or a pattern with a ! character causes hosts that match that entry to be excluded. 

An mdirect entry also contains a hostnameor pattern, but followsit with a list of hostnamesor macrosto which indirect 
queries should besent. 

A macro definition contains a macro name and a list of hostnamesand other macrosthat the macro expandsto. To 
distinguish macrosfrom hostnames, macro names start with a% character. M acros may be nested. 

mdirect entri es may also specify to havexdm run chooser to offer a menu of hosts to connectto. Seethesubsection 



<XRoot>. 



XDMCPACCESSCONTROL 



"chooser. 



xdm 



When checking access for a particular display host, each entry isscanned in turn and the first matching entry determi nes the 
response. Direct and Broadcast entries are ignored when scanning for an mdirect entry and viceversa. 

Blank li nes are ignored, # istreated asacomment deli miter causi ng the rest of that lineto be ignored, and Wwiine causesthe 
newlineto be ignored, allowing indirect host liststo span multi pie li nes. H ereisasamplexaccess file 

# 

# Xaccess - XDMCP access control file 
# 

# 

# Direct/Broadcast query entries 
# 

lxtra.lcs.mit.edu # disallow direct/broadcast service for xtra 
bambi.ogi.edu # allow access from this particular display 
.lcs.mit.edu # allow access from any display in LCS 
# 

# Indirect query entries 
# 

%HOSTS expo.lcs.mit.edu xenon.lcs.mit.edu \ 

excess.lcs.mit.edu kanga.lcs.mit.edu extract.lcs.mit.edu xenon.lcs.mit.edu #force extract to contact xenon 
!xtra. lcs.mit . edu dummy #disallow indirect access 
.lcs.mit.edu %HOSTS #all others get to choose 

chooser 

For X termi nals that do not offer a host menu for usewith Broadcast or indirect queries, the chooser program can do this 
forthem. In thexaccess file, speci fy chooser as the first entry in the indirect host list, chooser will send a Query request to 
each of the remai ni ng hostnamesin the list and offer a menu of ali the hosts that respond. 

The list may consistof the word broadcast, in which case chooser will send a Broadcast instead, again offerì ng a menu of ali 
hosts that respond. N otethat on some operati ngsystems, U D P packetscannot be broadcast, so thisfeaturewill notwork. 

Example xaccess file using chooser: 

extract.lcs.mit.edu CHOOSER %HOSTS #offer a menu of these hosts 
xtra.lcs.mit.edu CHOOSER BROADCAST #offer a menu of ali hosts 

Theprogram to use for chooser isspecified by theDispiayManager.D splay .chooser resource For moreflexibility atthisstep, 
the chooser could be a shell script, chooser isthesession manager here; it isrun instead of achild xdm to manage the di splay. 

Resources for this program can be put into thefilenamed by DispiayManager.Di splay .resources. 

When the user selectsa host, chooser prints the host chosen, which isread by theparentxdm, and exits. xdm closesits 
connection to theX server, and the server resetsand sendsanother indirect XDMCP request. xdm rememberstheuser's 
choice(forDispiayinanager. choiceTimeout seconds) and forwards the request to the chosen host, which startsa session on that 
display. 

LOCAL SERVER SPECIFICATICI 

TheresourceDispiayManager.servers givesaserver specifi cation or, if the values starts with aslash (/), thenameof afile 
contai ning server speci fi cations, oneper line. 

Each specificati on indicates a display which should constantly bemanaged and which is not using XD M CP. This method is 
used typically for locai serversonly. If the resource or thefilenamed by the resource isempty, xdm will offer XD M CP service 
only. 

Each speci fi cation consists of at least three parts: a display name, a display class, a display type, and (for locai servers) a 
command lineto start the server. A typical entry for locai display number 0 would be 

:0 Digital-QV locai /usr/X11R6/bin/X :0 
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T he display types are 

Locai locai display: xdm must run theserver 

Foreign remote display: xdm opensan X connection to a running server 

The display namemust besomethingthat can bepassed in the -display option to an X program. Thisstring isused to 
generate the display-specific resource names, so becareful to match thenames(forexample, use :a sun -cG3 locai /usr 
/xiiR6/bin/x : 0 i nstead of ìocaihost : 0 Sun-CG3 locai /usr/xi 1R6/ bin/x :0 if your other resources are specified as 
DispiayManager.^0.session). The di splay class portion isalso used in the display-specific resources, as the class of the 
resource. Thisisuseful if you havea largecollection of similar displays (such as a corrai of X termi nals) and would liketo set 
resources f or groupsof them. When usi ng XDM CP, the display isrequired to specify the display class, so themanual for 
your particular X terminal should document the display class stri ng for your device. If it doesn't, you can run xdm in debug 
mode and look at the resource stri ngsthat it generatesforthat device, which will include the class string. 

When xdm startsa session, it setsup authorization data for the server. For locai servers, xdm passes-auth menarne on the 
server'scommand lineto point it at its authorization data. For XDM CP servers, xdm passes the authorization datato the 
server via the Accept XDM CP request. 

RESOURCES FILE 

Thexresources fi le is loaded onto thedisplay as a resource database usi ngxrdb. Astheauthentication widget readsthis 
database before starti ng up, it usuai ly contai nsparameters for that widget: 

xlogin*login . translations : #override\ 
Ctrl<Key>R: abort -display! ) \n\ 

<Key>F1 : set-session-argument(failsafe) f inisb-f ield ( ) \n\ 
<Key>Return: set -session-argument ( ) f inisb -f ield( ) 
xlogin*borderWidth : 3 
xlogin*greeting: CLIENTHOST 
#ifdef COLOR 

xlogin*greetColor: CadetBlue 
xlogin*failColor: red 
#endif 

Please note the translations entry; it specifies a few new translations for the widget that allow usersto escape from the default 
session (and avoid troublesthat may occur in it). N otethat if #override isnot specified, the default translations are removed 
and replaced by the new value, not a very useful result as some of the default translations are quiteuseful (such as«ey>: 
insert-char <), which respondsto normal typing). 

Thisfile may also contain resources for the setup program and chooser. 
SETUP PROGRAM 

T he xsetup file is run after the server is reset, but before the Logi n window is offered. T he fi le is typically a shel I script. It is 
run asroot, so you should becareful about security. Thisis the placete changetheroot background or bring up other 
Windows that should appear on thescreen along with the Logi n widget. 

In addition to any specified by DispiayManager.exportList, thefollowingenvironment vari ables are passed: 
display Theassociated display name 

PATH Thevalueof DisplayManager.DI SPLAY .systemPath 

SHELL Thevalueof DisplayManager.DI SPLAY .systemShell 

xauthority M ay be setto an authority file 

N otethat si nce xdm grabs the keyboard, any other Windows will not beableto receive keyboard input. They will beableto 
interact with the mouse, however; bewareof potential security holes here. If DisplayManager.DI splay .grabserver is set, xsetup 
will not beableto connect to thedisplay at ali. Resources for this program can beput into thefilenamed by 

DisplayManager.DI SPLAY .resources. 




H ere i s a sam pi e xsetup seri pt: 

#!/bin/sh 

# Xsetup 0 - setup script for one workstation 
xcmsdb </usr/X1 1 R6/lib/monitors/alex.0 

xconsole -geometry 480x130-0-0 -notify -verbose -exitOnFail & 



AUTH ENTICATIO N WIDGET 

Theauthentication widget reads a nam e/ password pairfrom thekeyboard. N early every imaginableparameter can be 
controlied with a resource Resources for this widget should beput into thefilenamed by DispiayManager.Di splay .resources. 
Ali of these have reasonable default values, so it is not necessary to speci fy any of them. 



xlogin 


, Login 


, width, 


The geometry of the Login widget is normally corri puted 


xlogin 


. Login 


. height, 


automati cai ly. If you wish to position it elsewhere, specify each 


xlogin 






of these resources 


xlogin 


.Login 


■ y 




xlogin 


.Login, 


foreground 


Thecolor used to display the typed- in username. 


xlogin 


. Login . 


font 


Thefontused to display thetyped-in username. 


x Xo Q i n . 


.Login 


. y i ce l ±i ly 


A stri nn which i denti fi ps thi s wi ndow The default i s x w-i ndnw 
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System. 


xlogin 


.Login, 


unsecureGreeting 


When X authorization isrequested in theconfiguration file 
for this display and none is in use, thisgreeting replacesthe 
standard greeting. The default is This is an unsecure session. 


xlogin 


.Login, 


greetFont 


The font used to display the greeting. 


xlogin 


, Login, 


greetColor 


Thecolor used to display the greeting. 


xlogin 


.Login, 


namePrompt 


The stri ng displayed to prompt for a username. xrdb stri ps 
trailingwhitespacefrom resource values, so to add spacesat 
theend of the prompt (usually anice thing), add spaces 
escaped with backslashes. The default is Login:. 


xlogin 


.Login, 


passwdPrompt 


Thestring displayed to prompt for a password. The default is 

Password : . 


xlogin 


.Login, 


promptFont 


Thefont used to display both prompts. 


xlogin 


.Login. 


promptColor 


Thecolor used to display both prompts. 


xlogin 


.Login, 


fail 


A messagethat isdisplayed when theauthentication fails. The 

default ÌS Login incorrect. 


xlogin 


, Login 


. failFont 


Thefont used to display the fai Iure message. 


xlogin 


.Login, 


f ailColor 


Thecolor used to di splay the fai Iure message. 


xlogin 


, Login, 


f ailTimeout 


Thenumber of secondsthat the fai Iure message isdisplayed. 
The default is3©. 


xlogin 


, Login, 


translations 


This specifies the translations used for the login widget. Refer 



to theX Tool kit documentation for a compi etedi scussi on on 
translations. The default translation tableis 
Ctrl<Key>H delete-previous-character() \n\ 

Ctrl<Key>D delete-character( ) \n\ 

Ctrl<Key>B move-backward -character( ) \n\ 

Ctrl<Key>F move-forward-character( ) \n\ 

Ctrl<Key>A move-to-begining( ) \n\ 

Ctrl<Key>E move -to- end ( ) \n\ 
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Ctrl<Key>K 


erase-to-end-of -line( ) \n\ 




Ctrl<Key>U 


erase-line() \n\ 




Ctrl<Key>X 


erase-line() \n\ 




Ctrl<Key>C 


restart -session ( ) \n\ 




Ctrl<Key>nn 


abort -sessioni) \n\ 




<Key>BackSpace 


delete -previous-character() 


\n\ 


<Key>Delete 


delete - previous -character ( ) 


\n\ 


<Key>Return 


finish-field() \n\ 




<Key> 


insert-char( ) \ 





The action s that are supported by the widget are 

delete -previous -character 
delete-character 
move -backward- character 
move -forward- character 
move-to-begining 

move-to-end 
erase-to-end-of -line 
erase -line 
finish-field 



abort-session 
abort -display 



E rases the character before the cursor. 
E rases the character after the cursor. 
M oves the cursor backward. 
M oves the cursor forward. 

(Apologies about the spelli ng errar.) M oves the cursor to the 
begi n n i n g of th e ed i tabi e text. 
M oves the cursor to the end of the editable text. 
E rases al I text after the cursor. 
E rases the enti re text. 

If the cursor isin thename field, proceedsto the password field; 
if thecursor isin the password field, checksthecurrent name/ 
password pai r. If the name/password pai r is vai id, xdmstartsthe 
session. Otherwise, thefailuremessageisdisplayed and the 
user isprompted again. 
T ermi nates and restarts the server. 
Termi nates the server, disabling it. T hi s action isnot accessi ble 
in the default confi guration. There are various reasonsto stop 
xdmon a system console, such aswhen shutting the system 
down, when usi ng xdmsheii, to start another type of server, or 
to generally access the console. Sending xdm a sighup will 
restart the display. Seethesubsection "Controlli ngXD M ." 
ResetstheX server and startsa new session. Thiscan beused 
when the resources have been changed and you want to test 
them or when thescreen hasbeen overwritten with system 
messages. 

I nserts the character typed. 

Specifies a single word argument that ispassed to the session at 
startup. Seethesubsection "Session Program." 
D isables access control in the server. Thiscan beused when 
the .xauthonty fi le cannot be createci byxdm. Bevery careful 
usi ng this; it might be better to di sconnect the machine from 
the network before doing this. 

STARTUP PROGRAM 

Thexstartup fi le is typi cai ly ashell script. It isrun asroot and should bevery careful about security. Thisis the placete put 
commands that add entriesto /etc/utmp (thesessreg program may beuseful here), mount users' home di rectories from file 
servers, display the message of the day, or abort the session if logins are not allowed. 



restart-session 



insert-char 
set-session-argument 

allow-all-access 



xdm 

In additi on to any specified by DispiayManager.exportList, thefollowingenvironment vari ables are passed: 



display Theassociated display name 

home The initial working directory of the user 

user Theusername 

PATH Thevalueof DisplayManager.DI SPLAY .systemPath 

SHELL Thevalueof DisplayManager.DI SPLAY .systemShell 

xauthority M ay be setto an authority file 



N o arguments are passed to the seri pt. xdm waits unti I this seri pt exits before starti ng the user sessi on. I f the exit value of thi s 
script is non-zero, xdm disconti nues the session and starts another authenti cation cycle. 

Thesamplexstartup fileshown here prevents login whi le the fi le /etc/noiogin exists. Thus, this is nota complete exam pie, 
but simply a demonstration of the availablefunctionality. 

H ere i s a sam pi e xstartup seri pt: 

#!/bin/sh 

# 

# Xstartup 
# 

# This program is run as root after the user is verified 
# 

if [ -f /etc/nologin ]; then 
xmessage -file /etc/nologin 
exit 1 

fi 

sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 

/usr/X11R6/lib/xdm/GiveConsole 

exit 0 

SESSION PROGRAM 

Thexsession program isthecommand that isrun as the user's session. It isrun with thepermissionsof theauthorized user. 
In addition to any specified by DispiayManager.exportList, thefollowingenvironment vari ables are passed: 



DISPLAY 


Theassociated display name 


HOME 


The initial working directory of the user 


USER 


Theusername 


PATH 


Thevalueof DisplayManager.DI SPLAY .userPath 


SHELL 


The user's default shdl (from getpwnam) 


AUTHORITY 


M ay be setto a nonstandard authority file 


KRB5CCNAME 


M ay be setto a Kerberos credenti als cache file 



At most instai lati ons, xsession should look in $home for afilexsession, which containscommandsthat each user would like 
to use as a session. xsession should also implementa system default session if no user-specified session exists. Seethe 
subsection "Typical U sage." 

An argument may be passed to this program from the authenti cation widget usingtheset-session-argument action. Thiscan 
beused to select different stylesof session. Onegood use of this featureisto allow the user to escape from the ordì nary 
session when it fails. Thisallowsusersto repair their own .xsession if it fails, without requiring admi ni strati ve intervention. 
Theexamplefollowingdemon strates this f eatu re. 

Thisexamplerecognizesthespecial failsafemode, specified in thetranslationsin thexresources file to provide an escape 
from the ordì nary session. It also requires that the .xsession filebeexecutableso you don't haveto guesswhat shell it wants 
to use. 
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#!/bin/sh 
# 

# Xsession 
# 

# This is the program that is run as the client 

# for the display manager, 
case $# in 

D 

case $1 in 
failsafe) 

exec xterm -geometry 80x24-0-0 

esac 
esac 

startup=$HOME/ .xsession 
resources=$HOME/ .Xresources 
if [ -f "Sstartup" ]; then 

exec "$startup" 
else 

if [ -f "$resources" ]; then 
xrdb -load "Sresources" 

fi 

twm & 

xman -geometry +10-10 & 

exec xterm -geometry 80x24+10+10 -ls 

fi 

Theuser's .xsession filemight look something likethefollowing example. D on't forget that the file must haveexecute 
permission. 

#! /bin/csh 

# no -f in the previous line so .cshrc gets run to set $PATH 
twm & 

xrdb -merge "$HOME/ .Xresources" 
emacs -geometry +0+50 & 
xbiff -geometry -430+5 & 
xterm -geometry -0+50 -ls 

RESET PROGRAM 

Symmetrical with xstartup, thexreset script isrun after the user session has ter minateci. Run asroot, itshould contai n 
commands that undo the effects of commands in xstartup, removi ng entri esfrom /etc/utmp or unmounting di recto ri es fra m 
fi le servers. The environment vari ables that were passed to xstartup arealso passed to xreset. 

A sample xreset script: 

#!/bin/sh 
# 

# Xreset 
# 

# This program is run as root after the session ends 
# 

sessreg -d -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 

/usr/X11R6/lib/xdm/TakeConsole 

exit 0 

CONTROLLINO THE SERVER 

xdm controis locai servers using PO SIX signals. sighup isexpectedto reset the server, dosi ng al I client connections and 
performing other cleanup duties. sigterm isexpected to termi nate the server. If these signals do not perform theexpected 

actions, theresources DisplayManager. DISPLAY. resetSignal and DisplayManager. DISPLAY. te rmSignal Can Specify alternate 

signals. 



xdm 



To control remote termi nals not usingXD M CP, xdm searchesthewindow hierarchy on the display and uses the protocol 
request Kmciient in an attempt to clean up the terminal forthenext session. Thismay not actually kill ali of theclients, as 
only thosewhich havecreated windowswill benoticed. xdmcp providesa moresure mechanism; when xdm closes its i nitial 
connection, the session is over and the terminal isrequired to dose ali other connections. 



xdm respondsto two signals: sighup and sigterm. When sent asiGHUP, xdm rereads the configurati on file, the access control file, 
and the servers file. Fortheserversfile, it noticesif entrieshavebeen added or removed. If a new entry hasbeen added, xdm 
starts a session on theassociated display. Entriesthat havebeen removed aredisabled immediately, meaning that any session 
in progress wi II beterminated without noticeand no new session will bestarted. 

When sent a sigterm, xdm termi nates ali sessions in progress and exits. Thiscan beused when shutting down the system. 

xdm attemptsto mark its vari oussubprocessesfor ps(l) by editing the command-l ine argument list in place. Becausexdm can't 
allocate additional space forthis task, itisuseful to start xdm with a reasonably long command line (using the full pathname 
should beenough). Each processwhich is servicing a display ismarked -display. 



You can use xdm to run a single session at a ti me, using the 4.3 init optionsor other suitabledaemon byspecifying the server 
on the command line: 

xdm -server " :0 SUN-3/60CG4 locai /usr/X1 1R6/bin/X :0" 

Or you might haveafileserver and acollection of X termi nals. The configuration forthis i sideriti cai to that of the precedi ng 
sample, exceptthexservers filewould look likethis: 

extol:0 VISUAL-19 foreign 

exalt:0 NCD-19 foreign 

explode:0 NCR -TOWERVIEW3000 foreign 

Thisdirectsxdm to manage sessions on ali threeof these termi nals. Seethesubsection "C ontrolling xdm" for a descri ption of 
using si gnalsto enableand disable these termi nals in amanner reminiscent of imt(8). 



Onething that xdm isn'tvery good at doing iscoexisting with other window systems. To use multi pie window systemson the 
same hardware, you'll probably bemoreinterested in xinit. 



CONTROLLINO xdm 



OTHER PO SSIBILITIES 



LIMITATIONS 



FILES 



<XRoot>/lib/X1 1 /xdm/A<display>-<suf f ix> 
/tmp/K5C<display> Kerberos 



<XRoot>/lib/X1 1 /xdm/xdm-config 
SHOME/ .Xauthority 
<XRoot>/lib/X1 1 /xdm/chooser 



<XRoot>/bin/X11 /xrdb 



<XRoot>/bin/X11/X 



<XRoot>/bin/X1 1 /xterm 



The default configuration file 

User authorization filewherexdm stores keysfor clientsto read 

The default cnooser 

The default resource database loader 

The default server 

The default session program and failsafeclient 
Thedefault place for authorization files 
C red enti als cache 



N ote: <xRoot> refers to the root of the X 11 instali tree. 



See Also 

x(l), xinit(l), xauth(l), Xsecurity(l), sessreg(l), Xserver(l) 

X Display Manager Control Protocol 
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AUTHOR 

Keith Packard (M IT X Consortium) 

X Versori 11 Releas96 

xdpyinfo 

xdpyinfo— D isplay information utility forX 
SYNOPSIS 

xdpyinfo [-display di spi ayname] [-queryExtensions] [-ext extensi on - name ] 

DESCRIVO N 

xdpyinfo is a utility for displaying information aboutan X server. It isused to examinethecapabilitiesof a server, the 
predefined valuesfor variousparametersused in communicating between clientsand the server, and thedifferent typesof 
screens and visualsthat are available. 

By default, numeric information (opcode, baseevent, base errar) about protocol extensionsisnotdisplayed. Thisinforma- 
tion can beobtained with the -queryExtensions option. Useof thisoption on servers that dynamically load extensionswill 
likely cause ali possibleextensionsto beloaded, which can beslow and can consume si gnificant server resources. 

Detailed information about a particular extension isdisplayed with the -ext extensionName option. If extensionName isall, 
information about ali extensi onssupported by both xdpy info and theserver isdisplayed. 

ENVIRONMENT 

display To get the default host, display number, and screen 

SEE ALSO 

x(l), xwininfo(l), xprop(l), xrdb(l) 

AUTHOR 

J im Fulton (M IT X C onsortium) 

X Veraon 11 Release6 

Xf86_Accel 

xF86_Accei— Accelerated X W indow System servers for U N IX on x86 platformswith an S3, M ach8, M ach32, M ach64, 
P9000.AGX, ET4000/W32, or8514/A accderator board 

SYNOPSIS 

XF86_S3 [ :displaynumber] [ option ] ... 
XF86_Mach8 [ : displaynumber] [ option ] ... 
XF86_Mach32 [idisplaynumber] [ option ] ... 
XF86_Mach64 [idisplaynumber] [ option ] ... 
XF86_P9000 [idisplaynumber] [ option ] ... 
XF86_AGX [idisplaynumber] [ option ] ... 
XF86_W32 [idisplaynumber] [ option ] ... 
XF86_8514 [idisplaynumber] [ option ] ... 



xf86_Accel 



DESCRIPTION 

XF86_S3 isan 8-bit PsaidoColor, 16-bit TrueColor and 24-bitTrueColor server for S3 graphic accelerator boards. N ote, 16- 
bit and 24-bit operation is not supported on ali S3 accelerator boards. Refer to readme.s3 for details of which boards are 
supported at which depths. 

xF86_Mach8 isan 8-bit PseudoColor server for ATI M ach8 graphic accelerator boards. 

xF86_Mach32 isan 8-bit PseudoC olor and 16-bit TrueColor server for ATI M ach32 graphic accelerator boards. N ote, 16-bit 
operation is not supported on ali M ach32 accelerator boards. 

xF86_Mach64 isan 8-bit PseudoColor, 16-bit TrueColor, and 24-bit TrueColor server for ATI M ach64 graphic accelerator 
boards. N ote, 16-bit and 24-bit operation isnot supported forali RAM DACs. Referto README.Mach64 for details of which 
RAM DACs are supported at which depths. 

XF86_P9000 isan 8-bit PseudoColor, 16-bit TrueColor, and 24-bit TrueColor server for Weitek Power 9000 (P9000) graphic 
accelerator boards. 

xf86_agx isan 8-bit PseudoColor and 16-bit TrueColor server forAGX/XGA graphic accelerator boards. 

XF86_W32 isan 8-bit PseudoC olor server for ET4000/W 32, ET4000/W32Ì, and ET4000/W32p graphic accelerator boards. 

xf86_8514 isan 8-bit PseudoC olor server for 8514/A graphic accelerator boards. 

Thesearederived from thex386 server provided with X11R5, and from thexssH server developed by Kevin M artin 

(<martin@cs.unc.edu>). 

CO NFIGU RATIO NS 

The servers support the followi ng chi psets 

XF86_S3 86C911, 86C924, 86C801, 86C805, 86C805Ì, 86C928, 86C928- P, 

86C732 (Trio32), 86C764 (Trio64>, 86C864, 86C868, 86C964, 86C968 

XF86_Mach8 AT I Mach8, AT I Mach32 

XF86_Mach32 ATI Mach32 

XF86_Mach64 ATI Mach64 

XF86_P9000 Diamond Vi per vlb, Diamond Viperpci, Orchid P9000, and 

some clones (W eitek P9000) 

XF86_AGX AGX-010, AGX-014, AGX-015, AGX-016, XGA-1, XGA-2 

XF86_W32 ET4000/W32, ET4000/W32Ì, ET3000/W32p 

XF86_85H IBM 8514/A and true clones 

ForS3, virtual resoluti onsup to (approximately) 1,152x800 are supported, using(up to) 1M B of display memory (the 53 
usesan internai width of 1,280 exceptfornew revisionsof someof thechips, hencelM B can't support 1,152x900). Physical 
resolutionsup to 1,280x1,024 (1,600x1,280 on somecards) are possi ble usi ng 2M B or more of display memory. (Virtual 
resolution isdependent solely on theamount of memory installai, with the maximum virtual width bei ng 2,048, and 
maximum virtual height is 4,096.) 

Similar resoluti ons are supported on theM ach64. Referto README.Mach64 for configuration details. 

Similar resolutions are supported on theM ach32. For theM ach32, the maximum virtual width is 1,536, and the maximum 
virtual height is 1,280. 

For M ach8, the maximum virtual width is 1,024. 
For 8514, the maximum resolution is 1,024x768. 

FortheAGX chips, maximum resolution dependsupon the chip revision and amount of available display memory. Referto 
README.agx for configuration details. 
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FortheP9000, the vi rtual and physical resolutions must bethesame With sufficient memory, resolutionsup to 
1,280x1,024 aresupported. 

Ali theserversthat support 24-bit visuals do so using a 32-bit per pixel configuration where8 bits in every 32 bits isunused. 
Thisneedsto betaken into account when calculating the maximum vi rtual display sizethatcan besupported atthisdepth. 

0PTI0NS 

In additi on to thenormal server optionsdescribed in thexserver(l) manual page, these servers accept some more command- 
lineswitches, asdescribed in thexFree86(l) man page. 

TheM ach64, M ach32, S3, P9000, and AGX servers now support morethan 8-bit color. The M ach32 and AGX servers 
support 16-bitTrueColor and theM ach64, 53, and P9000 servers support 16-and 32-bit TrueColor. The 32-bit TrueColor 
modeonly uses24 bits per pixel for color informati on (givingyou 16 mi Ili on colors). These modesmay beused by 
specifyingthe-bpp option asspecified in thexFree86(l) man page. 

SETUP 

xFree86 uses a configuration filecalled xF86Config for ite initial setup. 

SeethexF86Config(4/5) man page for general details. H ere only the parte specific to thexF86_s3, xF86jiach8, xF86_Mach32, 
xF86_Mach64, XF86_P9O00, xf86_agx, xf86_w32, and xf86_8514 servers are explained. 

EntriesfortheDevice section in thexF86Config fi le include the following: 

chipset "name" Specifies a chipset so the correct driver can be used. Possible 

chipsets are 

XF86_S3 

S3_generic: (for a standard IO-driven server) 
Mmio_928: (for a memory-mapped IO-driven server on 
86C928, 86C732, 86C764, 86C864, 86C868, 86C964, and 
86C968 boards) 

xF86_Mach8, Machs (to forcethe M ach8 server to run on 
M ach32 boards) 

XF86_Mach32, Mach32 
XF86_Mach64, Mach64 
XF86_P9000 

vipervib (for the D iamond V i per V LB) 
viperpci (for the D iamond V i per PC I ) 
orchidp9000 (for the 0 rchid P9000 and many 
generic P9000-based boards) 

XF86_AGX 

Agx-016 

Agx-015 

Agx-014 

Agx-010 

Xga-2 

Xga-1 



NOTE 



Only the agx-016, agx-015, agx-014, and xga-2 havebeen tested. Referto the xga and agx -010 section of README.agx before 
attempting to usetheother chipsets. 



Clocks clock 



ClockChip "ci ockchi p-type" 



Ramdac " r a md a c - 1 y p e " 
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XF86 W32 

Et4000w32 
Et4000w32Ì 
Et4000w32i_rev_b 
Et4000w32i_rev_c 
Et4000w32p_rev_a 
Et4000w32p_rev_b 
Et4000w32p_rev_c 
Et4000w32p_rev_d 

XF86_8514 

Ibm8514 

For boardswith nonprogrammable clock chips, the clocks can 
bespecified here(seexF8econfig(4/5)). TheP9000 server now 
no longer requiresaciocks line It will now work thesame 
way asother serverswith a programmable clock chip (that is, 
use the clocks asspecified in the M odes). N ote, clocks over 
110 M H z are not recommended or supported by the P9000 
server. The M ach64 server also doesnot requireaciocks line 
because the clocks are normally read directly from the video 
card'sBIOS. For the M ach64 server, the clocks given in the 
xF86Config file are ignored unlesstheno_bios_ciocks option is 
given (seebelow). 

For boardswith programmable clock chips(exceptwith the 
P9000 and AG X servers), the nameof the clock chip is given. 
Possible values for the 53 server include M icd206ia", 

"ics9161a", "dcs2834", "sci 1412", "s3gendac", "s3 sdac", 
"ti3025", "ti3026", "ÌCS2595", "ÌCS5300", "ÌCS5342", "ch8391", 
"stg1703", and "ibm_rgb5xx" . 

T his specifies the type of RAM DAC used on the board. 0 nly 
theS3, AGX, and W 32 servers use this. 
Normai— (53, AG X ) C ard does not have one of the other 
RAM DACsmentioned here. Thisoption isonly required for 
theS3 server if the server incorrectly detects one of those other 
RAM DACs. TheAGX server does not yet auto-detect 
RAM DACs, this is the default if no RAM DAC isspecified. 
Generic— (W 32) T hi s forces the W 32 server to treat the 
RAM DAC asagenericVGA RAM DAC. 
Att20c490- (S3, AGX) Card hasan AT&T 20C490 or AT&T 
20C491 RAM DAC. When thedac_8_bit option isspecified, 
theseRAM DACsmay beoperated in 8-bit per RGB mode. It 
also allows 16bpp operation with 801/805/928 boards True 
AT&T 20C490 RAM D ACsshouId be autodetected by the S3 
server. This RAM DAC must bespecified explicitly in other 
cases. N ote that 8-bit per RGB mode does not appearto work 
with theWinbond 82C490 RAM DACs(which SuperProbe 
identifiesasAT&T 20C492). 16bpp worksfinewith the 
Winbond 82C490. TheD iamond SS2410 RAM DAC is 
reported to be compati ble when operating in 15bpp mode 
(not 16bpp). TheChrontel 8391 appearsto be compati ble in 
ali modes. 
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sci 5025- (S3, AG X ) C ard has a Sierra SC 15025 or SC 15026 
RAM DAC. TheS3 server has code to autodetect this 
RAM D AC . 

sci 1 482- (S3) C ard has a Si erra SC 11482, SC 11483, or 
SC 11484 RAM D AC . TheS3 server hascodeto autodetect 
thisRAM DAC. 

Scii485- (S3) Card has a Sierra SC 11485, SC 11487 or 

SC 11489 RAM DAC. TheS3 server wi II detectthese 

RAM DACsasan scH482, so this option must bespecified to 

take advantage of extra features (they support 16bpp, 15bpp, 

and 8bpp, whiletheothersonly support 15bpp and 8bpp). 

Bt485- (s3) C ard has a B rookT ree Bt485 or Bt9485 

RAM DAC.Thismust bespecified if the server fai I sto detectit. 

Att2Oc505-(S3) Card hasan AT&T 20C505 RAM DAC. 
This must be specified either if the server failsto detect the 
20C 505, or if the card has a Bt485 RAM D AC and there are 
problems using clocks higher than 67. 5M Hz. 

Att20c498-(S3)Card hasan AT&T 20C498or21C498 
RAM DAC.Thismust bespecified if the server failsto detectit. 
Att22c498-(S3)Card hasanAT&T 22C498 RAM DAC . 
This must bespecified if the server failsto detect it. 
Ibm_rgb5i4-(S3) Card hasan IBM RGB514 RAM DAC. This 
must be specified if the server failsto detect it. 
ibm_rgb524— (S3) Card hasan IBM RGB524 RAM DAC. This 
must be specified if the server failsto detect it. 
ibm_r-gb525 — (s3) Card hasan IBM RGB525 RAM DAC. This 
must be specified if the server failsto detect it. 
ibm_rgb528— (S3) Card hasan IBM RGB528 RAM DAC. This 
must be specified if the server failsto detect it. 

Stg1700— (S3) Card has an STG1700 RAMDAC. T his must be 

specified if theserver failsto detect it. 

Stg1703— (S3) Card has an STG1703 RAMDAC. T his must be 

specified if theserver failsto detect it. 

S3gendac-(S3) Card hasan S3 86C708 GEN DAC. This 

RAM DAC doesnot support 8-bit per RGB mode(don't 

speci fy the dac_8_bit option). Itallows 16bpp operation with 

801/805 boards. There iscurrently no autodetection forthis 

RAMDAC. 

S3_sdac-(S3) Card hasan S3 86C716 SD AC RAM DAC. 
This must bespecified if the server failsto detectit. 

ics5300-(S3) Card hasan ICS5300 RAM DAC. Thismust be 

specified if theserver failsto detect it (theserver wi II recognize 

thisasan S3 GEN DAC which isOK). 

ics5342-(S3) Card hasan ICS5342 RAM DAC. Thismust be 

specified if theserver failsto detect it (theserver wi II recognize 

thisasan S3 SDAC which isOK). 

Ti3020-(S3) Card hasaTI ViewPointTi3020 RAM DAC. 

Thismust bespecified if the server failsto detect theTi3020. 

N otethat pixel multiplexingwill beused forthis RAM DAC if 

any mode requi resa dot clock higher than 70M Hz. 
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tì3025-(S3) Card hasaTI V iewPoint T Ì3025 RAM DAC. 
Thismust bespecified if the server fai Isto detecttheTi3025. 
tì3026-(S3) Card hasaTI ViewPointTi3026 RAM DAC. 
Thismust bespecified if the server fai Isto detect theTi3026. 
Bt48i-(AGX) Card hasa BrookTree Bt481 RAM DAC. 
Bt482-(AGX) Card hasa BrookTree Bt482 RAM DAC. 
Herc_duai_dac— (AGX) Card (H ercules G raphite Pro) has 
both the84-pin (Bt485 or AT&T20C505) and 44-pin (Bt481 
or Bt482) RAM DACsinstalled. 
Herc_smaii_dac— (AGX) Card (H ercules G raphite Pro) has 
onlythe44-pin(Bt481orBt482) RAM DAC instali ed. 
ioBase ioaddress Specifies the base addressfor extended IO regi sters. Thisis 

only used by theAGX server, and by the P9000 server forthe 
Vi per PCI. For detailsof how to useit, referto README.agx and 

README.P9000. 

MemBase me ma d d r e s s Specifies the hard-wi red part of the li near framebuffer base 

address. Thisoption is only used by the P9000, S3, Mach64, 
and M ach32 servers(and only when using a linear 
framebuffer). For the S3 server, thehard-wired part is the high 
10 bits of the 32-bit address (that is, me ma d d r e s s ismasked with 
0xFFC0000o). N ote: Thisshould not berequired for the 864 
and 964 chi ps where the enti re framebuffer address is software- 
selectable. Also, note that in versi ons prior to 3.1.1, theS3 
server used only the top 6 bitsof me ma d d r e s s , and oRed it with 
0X3CO0000. To get thesamebehavior, or 0x3000000 with the 
value given previously. For the M ach32 server, the mask is 
0XF8000000 (exceptforPCI cards, where the membase setting is 
ignored). 

Thisoption must bespecified with the P9000 server. With 
locai busDiamond Vipersthevalueof memaddress can be 
either 0x80000000, 0x20000000, or 0XA0000000. The default is 
0x80000000. Any value should work aslong as it doesnot 
conflictwith another device al ready at that address. Forthe 
Viper PCI, referto readme.ps-ooo. FortheOrchid P9000, the 
base address may be 0x00000000, 0XD0000000, or 0XE0000000, 
and must correspond theboard'sjumper setting. N ote Thes3 
server wi II normally probe for this address automati cally. 
Setting thisoption overridesthat probe. Thisisnot normally 
recom m en ded because th e f ai I u re of th e server's probeusually 
indicates problems in usi ng the li near framebuffer. 



NOTE 



T he M ach64 server requires the memory aperture. For ISA bus video cards, this means that the aperture must beenabled 
and the aperture address must besettoavaluelessthan 16M B (which means that, on ISA systemsonly, to use the M ach64 
server you must have 12M B of main memory or less). N ormally the M ach64 server will use predefined valuesfor this 
address, but setting thisoption will overridethe predefined address. 

TheM ach32 server should not requi re the use of thisoption under normal circumstances. 
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COPBase baseaddress 
Instance i nst anc e 
S3MClk me me I k 

S3MNAdjust M N 
S3RefClk ref ci k 

Option flagsmay be specified in either the Device section 

Option "opti onstri ng" 



T his sets the coprocessor base address for the AG X server. 
Referto README.agx for details. 

ThissetstheXGA instance number for theAGX server. Refer 

tO README.agx for details. 

Thisallows thevideo card'smemory clock valueto be 
specified. Thisisonly used for 805i, 864 and Trio32/64 cards, 
and thevalueshould not normally begiven here for cards with 
an S3 Gendac or Trio64.T his entry doesn't changethecard's 
memory clock, but it isused to calculate the D RAM timing 
parameters. For further details refer to readme.s3. 
Thisallowssomememorytiming param eters to be adjusted 
for DRAM cards. For further details referto readme.s3. 
Thisallows thePLL reference clock to be specified. T his may 
berequired for some cards that use the IBM RGB5xx 
RAM DACs.Thevalueisin MHz. For further details referto 

README.S3. 

Or the Display SUbseCtion Of theXF86Config file. 

Allows the user to select certain optionsprovided bythe 
drivers. Currently thefollowing stri ngs are recognized: 
Nomemaccess— (53) D isable direct access to video memory. 
T his option is ignored for the 864 and 964 chips. 
Noaccei— (AGX, P9000) D isable hardware acceleration for the 
P9000, and disables the font cache with theAGX. 
vram_i28— (AGX, P9000) W hen memory probe fai I s, useif 
you havel28Kx8 VRAM s. 

vram_256— (AGX, P9000) W hen memory probe fails, useif 
you don't have 128Kx8 VRAM s. 
Noiinear— (S3 and M ach32) D isableuseof a linear-mapped 
fram ebuffer. 

Ti3020_curs— (53) E nables the Ti3020's internai HW cursor. 
(D efault) 

no ti3020_curs— (S3) D isables the Ti 3020's internai HW 
cursor. 

sw_cursor- (S3, M ach32, M ach64, P9000, AGX) D isablethe 
hardware cursor. 

Dac_8_bit- (S3, M ach32, M ach64, AGX) Enables8-bit per 
RGB. Currently only supported with theTi3020/5/6, Bt485, 

AT&T20C505, AT&T20C490/1, Sierra SC15025/6, AT8J20C498 and 

stgi 700/3, ibm rgb5xx (S3 server), Bt48i and Bt482 (AGX 
server), ati68875/tlc34075/bt885 (M ach32 server), ATI68875, 

TLC34075, ATI68860, ATI68880, STG1702, and STG1703 (M ach64 

server) RAM DACs. Thisisnow set by default in thes3 server 
when oneof the preceding RAM DACsotherthan the 

AT8J20C490/1 iSUSed. 

Dac_6_bit— (S3) Force 6-bit per RGB in caseswhere8-bit 
modewould automatically beenabled. 
sync_on_green— (53, P9000) E nables generation of sync on the 
green signal on cards with Bt485, AT&T20C505, TÌ3020/5/6 or 
ibmrgb5xx RAM DACs. N ote: Although theseRAM DACs 
support sync_on_green, it won't work on many cards because 
of theway they are desi gned. 
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Power_saver— (S3 and M ach64) Thisoption enables the serva- 
to use the power-savi ngfeaturesof VESA DPM S-compatible 
monitors. Thesuspend leve! iscurrently only supported forthe 
M ach64 and forthe 732, 764, 864, 868, 964, 968 S3 chips. Refer 
to the xF86Conf ig(4/5) manual page for detai Is of how to set 
thetime-outsfor the different levelsof 0 perati on. Thisoption 
is experi men tal. 

intei_gx— (M ach32) Sets thehard-wired offset for the linear 
framebuffer correctly for the Intel GX Pro cards. Thisoption 
isequivalentto setti ng the membase to 0x78000000. 
speajnercury— (S3) Enables pixel multiplex support for SPEA 
M ercury cards (928 +Bt485 RAM D AC). For these cards, pixel 
multi plexing isrequired in orderto use dot clocks higher than 
67.5 M H zand to access more than 1M B of video memory. 
Pixel multi plexing iscurrently supported only for 
noninterlaced modes, and modeswith aphysical width no 
smallerthan 1,024. 

stb_pegasus— (S3) Enables pixel multiplex support for STB 
Pegasus cards (928 +Bt485 RAM DAC). For these cards, pixel 
multiplexing isrequired in orderto use dot clocks higher than 
67.5 MHz. Pixel multiplexing iscurrently supported only for 
noninterlaced modes, and modeswith aphysical width no 
smallerthan 1,024. 

number_nine— (S3) Enables pixel multiplex support for 
NumberNineGXelevel 10, 11, 12 cards (928 +Bt485 
RAM DAC). For these cards, pixel multiplexing is required in 
orderto use dot clocks higher than 85M Hz. Pixel multiplexing 
iscurrently supported only for noninterlaced modes, and 
modeswith a physi cai width no smallerthan 800. Thisoption 
isalso required for some other N umber N ine cards (for 
example, gxe64 and GXE64pro). 
diamond— (S3) Thisoption may be required for some 
D iamond cards (in particular, the 964/968 VRAM cards). 
eisa_wi000pro— (s3) E nables support for the E LSA W inner 
1000 PRO. Thisoption isnotusually required becausethe 
board can beautodetected. 

eisa_wi000isa— (S3) E nablessupport for the E LSA Winner 
1000 ISA. Thisoption isnotusually required becausethe 
board can beautodetected. 

eisa_w2000pro— (s3) E nables support for the E LSA W inner 
2000 PRO. Thisoption isnotusually required becausethe 
board can beautodetected. 

pcijiack— (s3) Enables a workaround for problems seen with 
some PCI 928 cards on machineswith a buggy SM C U ART. 
s3_964_bt485_vcik— (S3) E nables a workaround for possi ble 
problems on cards usi ng the 964 and Bt485. 

genoa, stb, hercules, Or number_nìne,— (S3) T hese Options may 

be used to select different defaults for the blank delay settings 
foruntested cards with IBM RGB5xx RAM D AC sto avoid 
pixel-wrapping problems. 
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siow_vram— (s3> AdjuststheVRAM timingsfor cardsusing 
slow VRAM . T his is required for someD iamond Stealth 64 
VRAM and H erculesTerminator64 cards. 
Fast_vram— (s3) AdjuststheVRAM timi ngs for faster V RAM 
access. Therewill be display errors and pixel garbageif your 
card can't support it. 

siow_dram_ref resh— (S3) Adjusts the D RAM refresh for cards 
with slow DRAM to avoid linesof corrupted pixelswhen 
switching modes. 

No_biock_write— (Mach64) D isablesthe block write mode on 
certain typesof VRAM Mach64 cards. If noiseorshadows 
appear on thescreen, thisoption should remove them. 
Biock_write— (M ach64) Enablesthe block write mode on 
certain typesof VRAM Mach64 cards. NormallytheMach64 
server will automatically determine if the card can handle 
block write mode, but thisoption will overri de the probe 
result. 

No_bios_ciocks— (M ach64) The M ach64 server normally 
reads theclocksfrom the bios. Thisoption overridesthebios 
clocksand forces the server to usetheclocksgiven in the 

XF86Config file. 

Therearealso numeroustuningoptionsfortheAGX server. 
Referto README.agx for details. 

N otethat xFree86 has some internai capabilitiesto determi ne what hardware it isrunningon. Thus, normally the keywords 
chipset, ciocks, and videoram don't haveto be specified. But there may be occasi onswhen this autodetection mechanism 
fails, (for example, too high a load on themachinewhen you start theserver). For caseslikethis, oneshould first run the 
server on an unloaded machine, look at the results of the autodetection (that areprinted out during server startup), and then 
explicitly specify these parameters i n the configuration file It isrecommended that ali parameters, especially clock values, be 
specified in thexF86Config file. 



FILES 

<XRoot>/bin/XF86 S3 
<XRoot>/bin/XF86 Mach8 
<XRoot>/bin/XF86 Mach32 
<XRoot>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<XRoot>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Config 
<XRoot>/lib/X1 1 /XF86Conf ig 
<XRoot>/lib/X1 1 /doc/README .agx 
<XRoot>/lib/X11 /doc/README. P9000 
<XRoot>/lib/X1 1 /doc/README. S3 
<XRoot>/lib/X1 1 /doc/README .W32 



The 8-, 16-, and 24-bit color X server for S3 

T he 8-bit color X server for M ach8 

The 8- and 16-bit color X server for M ach32 

The 8-, 16-, and 24-bit color X server for M ach64 

The 8-, 16-, and 24-bit color X server for the P9000 

The8- and 16-bit color X server for AGX andXGA 

The 8-bit color X server for ET4000/W 32 

T he 8-bit color X server forIBM 8514 and truecompatibles 

Server configuration file 

Server configuration file (secondary location) 

Extra documentation for the AGX server 

Extra documentation for the P9000 server 

Extra documentation for the S3 server 

Extra documentation for the W 32 server 



N ote: <xRoot> refers to the root of the X 11 i nstall tree. 
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SEE ALSO 

x(l), Xserver(l), XFree86(l), XF86Conf ig(4/5), xvidtune(l), xdm(l), xf86conf ig(l), xinit(l) 

AUTHORS 

In additi on to theauthorsof xFreese thefollowing people contri buted major work to this server: Kevin M artin 
(martinecs.unc.edu), Jon Tombs (tombsexFree86.org), Rik Faith (t aitn?cs . une . edu). (D id the overall work on the base 
accelerated servers.) 

D avid Dawes (daweseXFree86.org), D irk H Ohndel (hohndeieXFree86.org), D avid W exelblat (dwexeXFree86.org). (M erged 

theirwork into xFree86.) 

Jon Tombs (tombsexFree86.org), D avi d W exelblat (dwexexFree86.org), David Dawes (dawesexFree86.org), Amando H asty 

(hastyenetcom.com), Robin Cutshaw (robineXFree86.org), N Orbert D istler (Norbert.Distlerephysik.tu-muenchen.de), Léonard 

N . Zubkoff (inzedandeiion.com), H arald Koenig (koenigetat.physik.uni-tuebingen.de), Bernhard Bender 
(breeisa.mhs.compuserve.com), H ans N asten (nasteneeveryware.se). (D evelopment and improvement of thes3-specific code.) 

Kevin M artin (martinecs.unc.edu), Rik Faith (faithecs.unc.edu), Tiago Gons (tiagoecomosjn.hobby.nl), H ansN asten 

(nasteneeveryware.se), Scott Laird (lairemidway.uchicago.edu). (D evelopment and improvement Of theMach8- and 851 4/ A- 

specific code.) 

Kevin M artin (martinecs.unc.edu), Rik Faith (faithecs.unc.edu), M ikeBernson (mikeembsun.mib.org), M ark W eaver 
(niarkweaverebrown.edu), Craig G roeschel (craigemetroiink.com). (D evelopment and improvement of the Mach32-specific code 

Kevin M artin, (martinecs.unc.edu). (D evelopment of the Mach64-specific code.) 

Erik Nygren (nygrenemit.edu), H arry Langenbacher (harryebrain.jpi.nasa.gov), Chris M ason 

(cimtcheosfmaii.isc.rit.edu), H enrik H armsen (harmseneeritei.se). (D evelopment and improvement of the P9oa0-specific 
code.) 

H enry Worth (henry.wortheamaii.amdahi.com). (D evelopment of theAGx speci fic code.) 
Glenn Lai (giennecs.utexas.edu). (D evelopment of the ET4000/w32-specificcode.) 
Seealso thexFree86(l) manual page. 

BUGS 

SomeS3 cardswith Bt485 RAM DACsarecurrently restri cted to dot-clocks lessthan 85M Hz. 

TheP9000 server may stili haveproblemswith cardsotherthan theD iamond Vi per VLB. Theremay stili beproblemswith 
VGA moderestoration, but theseshould almost never occur. Using physical resolutions different from the vi rtual resolution 
isnot supported and isnot possi blewith the P9000. U se at dot-clocks greater than 110M Hz isnot recommended and not 
supported. D iamond claimsthat 135M Hz isthe maximum clock speed, but someof its bt48ss are not rated that high. If you 
do not havea 135M H zbt485 on your Vi per, contact Diamond tech support and they wi II send you an RM A numberto 
replace the board. Accelerati on isbeing added in slowly. Atthepresent, only copyArea, Movewindow, and DrawLine are 
implemented. Other accelerated featuresarebeing tested and may beavailablein thenext release. Thereseemsto bea 
problem with oivwm when used with xdm and vt switching. Thecursorwill bemessed up when you return to avi if the cursor 
changed whileyou werein thevr. 

CONTACT INFO 

xFree86 source is avai lable from the FTP server ftp.xFree86.org and mirrors. Send e-mail to xFree86exFree86.org for details. 

xFree86 Versi on 3.1.2 
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XF86_Mono 

xF86_Mono— 1- bit nonacceìerated X Window System serversfor U N IX on x86 platforms 
SYNOPSIS 

XF86 Mono [ idisplaynumber] [ option ] ... 

DESCRIPTION 

xF86_Mono is a 1-bit Stati cG rey server for VGA and SuperVGA cards and for some other monochromecards. 
CO NFIGU RATIO NS 

ThexF86_Mono server supports the following popular SuperVGA chipsets in monochrome mode 

ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 

68800-6, 68800AX, 68800LX, 88800CX, 88800GX 

Tseng ET3000, ET4000, ET4000/W32 

Western D igital pvgm, WD90C00, WD90C10, WD90C11, WD90C30, WD9BC31, WD90C33 

G enoa gvga 

Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

NCR 77C22, 77C22E 

Compaq avga 

Oak OTI067, OTI077, OTI087 

CirrUS CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, CLGD5429, 

CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, CLGD6225, 
CLGD6235, CL6410, CL6412, CL6420, CL6440 

ThexF86_Mono server supports thefollowing monochromecards and resolutions: 

Sigma L-View, LaserView PLUS (in lbpp mode): 1,664x1,280 

Hyundai HGC-1280: l,280[l,472]xl,024 

Apollo M onochromecard (with ID 9) from Apollo workstations: 

1,280x1,024 

H ercules and compatibles cards 720x348 

Additi onally, it supports generic VGA cards with a maximum virtual resolution of (approximately) 800x650. 

On supported SVGA chipsets, xF86_Mono will useup to y 4 of display memory, which yields a maximum virtual resolution of 
(approximately) 1,664x1,260 with 1M B of display memory. xF86_Mono does not support the acce! erated functionsof the 
supported chipsets. 

0PTI0NS 

In additi on to thenormal server optionsdescribed in thexserver(l) manual page, xF86_Mono accepts some more command- 
lineswitches, asdescribed in thexFree86(l) man page. 

SETUP 

xFreese uses a configuration filecalled xF86Config for its initial setup. 

SeethexF86Config(4/5) man page for general details. H ere only the xF86_Mono specificpartsareexplained. 

The Driver entry in screen section of thexF86Config fi le should beset to vga2 for VGA and SVGA boards, and mono for non- 
VGA mono boards. If screen sections are present forbotti of these, the server will start in adual-headed configuration. 
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thefollowing: 

Specifies a chi pset so the correct driver can beused. Possi ble 
chipsetsforVGA2: 

ATI Vgawonder 

Tseng Et3000, et4000, et4000w32, et4000w32i, 

et4000w32p 

Western Digital Pvgai, wd9Bc0a, wd90cia, wd9ac30, 

Wd90c31, Wd90c33 

Genoa Gvga 

Trident Tvga8800cs, tvga8900b, tvga8900c, 

tvga8900cl, tvga9000 

NCR Ncr77c22, ncr77c22e Compaq: cpq avga 

OAK: oti067, oti077, oti087 

Cirrus Clgd5420, clgd5422, clgd5424, clgd5426, 

clgd5428, clgd5429, clgd5430, clgd5434, 
Clgd5436, clgd6205, clgd6215, clgd6225, 
clgd6235, C16410, C16412, C16420, C16440 

GenericVGA generic 

Possi ble chi psets for mono: 
Hyundai hgd280 

Sigma sigmalview 
Apollo apollo9 
Hercules hercules 

Specifies the base addressof thevideo memory. Thisoption is 
only used fortheSigma LaserViewcards. Valid addressesfor 
thesecardsare0xA0000, 0XB0000, 0x00000, 0x00000, 0XE0000. The 
default ÌS0XE0000. 

Setsthebiack color to the RGB values specified. Thesevalues 
must begiven asintegers in the range 0-63. The default isa 0 
0. Thisoption is only valid forthevga2 screen type. 
Setsthewhite color to theRGB values specified. Thesevalues 
must be given asintegers in the range 0-63. The default is 63 
63 63. Thisoption isonly valid forthevga2 screen type. 
Allows the user to select certain optionsprovided bythe 
drivers. Currently thefollowing stri ngs are recognized: 
ìegend— For Sigma Legend ET4000-based boards. This 
option enables a special clock-selection algorithm used on 
Legend boards, and M U ST be specified for these boards to 
function correrti y. 

swap_hibit— For Western D igital/PVGAl chi psets. Some 
Western D igital-based boards requi re the high-order clock- 
select lead to beinverted. It isnot possi ble for the server to 
determinethisinformation at run-time. If the 9th clock in the 
list of clocks detected by the server is lessthan 30M hz, this 
option likely needsto beset. 
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Hibit_iow, hibitjiigh— For Tseng ET4000 chipsets. W ith 
someET4000 cards, the server hasdifficulty getti ng the state 
of thehigh-order clocks select bit rightwhen started from a 
high-resolution text mode Theseoptionsallow thecorrect 
initial state ofthat bitto bespecified. To find outwhatthe 
correct initial state is, start the server from an 80x25 text 
mode. Thisoption isonly needed if the clocks reported bythe 
server when started from a high-resolution text mode differ 
from those reported when it is started from an 80x25 text 
mode. 

8ciocks— For the PV GAI chipset, the default is 4 clocks 
Somecardswith thischipset may support8 clocks. Specifying 
thisoption will allow thedriver to detect and usetheextra 
clocks. 

i6ciocks— ForTrident tvga8900b and 89000 chipsets. Some 
newer boardsusing 8900B and 8900C chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boardswill 
haveaTCK9002 oncK9004 chip on them. Specifying thisoption 
will allow the driver to detect and use the extra 8 clocks. 
Power_saver— Thisoption enables the server to use the power 
savi ngfeaturesof VESA D PM S-compati ble moni tors. The 
suspendlevel is currently not supportaci. Referto the 
xF86Config(4/5) manual pagefordetailsof how to set thetime- 
outsforthedifferent levelsof operation. Thisoption is 
experi men tal. 

secondary— For the hgd280 and apoiio9 chipsets. Thisoption 
allowstheuseof thesecardsjumpered to thesecondary 1/0/ 
memory address. These addresses are 

hgc1280: I/O 0X3B0-0X3BF, mem 0XB0000-0XBFFFF (prim.) 

I/O 0X390-0X39F, mem 0xC8000-0xCFFFF (seC.) 
apollo9: I/O 0X3B0-0X3BF, mem 0XFA0000 -0XFDFFFF (prim.) 

I/O 0X3D0-0X3DF, mem 0xA0000-0xDFFFF (seC.) 

xFree86 can detect the hgc- 1280 on both primaryand 
secondary address; for the apollo card theprimary address is 
used by default. 

N otethat xFree86 has some internai capabilitiesto determi ne what hardware it isrunningon. Thus, normally thekeywords 
chipset, ciocks, and videoram don't haveto bespecified. But there may be occasi ons when this autodetection mechanism 
fai Is, (for example, too high a load on the machine when you start the server). For cases li ke this, oneshould first run 
xF86_Mono on an unloaded machine, look at the results of the autodetection (that areprinted out during server startup) and 
then explicitly specify these parameters in theconfiguration file. Itisrecommended that ali parameters, especially clock 
values, bespecified in thexF86Config file 

FILES 

<XRoot>/bin/XF86 Mono 

/etc/XF86Config 
<XRoot>/lib/X1 1 /XF86Conf ig 



ThemonochromeX server forVGA, SVGA and other 
monochrome cards 
Server configuration file 
Server configuration file 



Note: <xRoot refersto therootof theXll instali tree. 
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SEE ALSO 

x(l), Xserver(l), XFree86(l), XF86Conf ig(4/5), xf 86conf ig(l), xvidtune(l), xdm(l), xinit(l) 

BUGS 

Thereareno known bugs at thistime, although wewelcomereportse-mailed to the address I isted below. 

CONTACT INFO 

xFreese source i s avai lable from the FTP serverttp.xFree86.org. 
Send e-mail to xFree86?xFree86.org for details. 

AUTHORS 

Referto thexFree86(l) manual page. 

XFree86 Versi on 3.1.2 

XF86JVGA 

xf86_svga— N onaccelerated SVGA X W indow System serversfor UNIX on x86 platforms 
SYNOPSIS 

XF86 SVGA [ idisplaynumber] [ option ] ... 

DESCRIPTION 

xf86_svga isan 8-bit PseudoColor, 16-bitTrueColor and 24-bitTrueColor server for SuperVGA cards. It isderived from 
thex386 server provided with xurs. N ote: 16-bitTrueColor iscurrently only supported for some Ci rrus and ARK chips, and 
24-bit T rueC olor is only supported for some C i rrus chi ps. 

CO NFIGU RATIO NS 

ThexF86_svGA server supportsthefollowing popular SuperVGA chipsets in 256-color mode. Virtual resolutionsup to 
(approximately) 1152x900 are supported, using(up to) 1M B of display memory. The Western D igital WD90C33 and someof 
the C i rrus chi psets support up to 2M B of display memory and virtual resolutionsof 1,280x1,024 and higher. Someof the 
Cirrus chipsets al so support 16bpp and 32bpp (truecolor) modeson certain configurations. Someof theARK chipsets 
support 16bpp modeson certain configurations. Generic VGA cards are also supported at 8bpp 320x200 only. 



ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 

68800-6, 68800AX, 68800LX, 88800CX, 88800GX 

Tseng ET3000, ET4000, ET4000/W32 

Western D igital pvgai, WD90C00, WD90C10, WD90C11, WD90C24A, WD90C30, WD90C31, 

WD90C33 

G enoa gvga 

Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

NCR 77C22, 77C22E 

CirrUS Logic CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, 

CLGD5429.CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, 
CLGD6225, CLGD6235, CL6410, CL6412, CL6420, CL6440 

ARK ARK1000PV, ARK1000VL, ARK2000PV 

RealTek RTG3106 
Compaq avga 

Oak OTI067, OTI077, OTI087 



Parti: U ser Commands 



Avance Logic 
Chips& Technology 
MX 

Video7 



AL2101, ALI2301, ALI2302, ALI2308, ALI2401 
65520, 65530, 65540, 65545 
MX68000, MX68010 
HT216-32 



Accelerateci support is included for most of the C irruschi psets, and for the Western D igital WD90C31 and WD90C33 chipsets. 
Accelerated support for the ET4000/W32 isimplemented in a separate server (seexF86_w32(l)). Usersof boards based on ATI's 
M ach8, M ach32, and M ach64 chipsets should referto thexF86_Mach8(l), xF86jiach32(l) and xF86_Mach64(l) manual pages, 
respectively. 

OPTIONS 

In additi on to thenormal server optionsdescribed in thexserver(l) manual page, xf86_svga accepts some more command- 
lineswitches, asdescribed in thexFree86(l) man page. 

SETUP 

xFree86 uses a configuration filecalled xF86Config for i ts i n i ti al setup. 

SeethexF86Config(4/5) man page for general details. HereonlythexF86_svGAspecificpartsareexplained. 
Thisserver requiresascreen section in thexF86Config fi le with theDriver entry setto svga. 
E ntries for the Device section in thexF86Config fileinclude 

chipset "nane " Specifies a chi pset so the correct driver can be used. Possible 

chipsets are 

ATI vgawonder 

Tseng et3000, et4000, et4000w32, 

et4000w32i, et4000w32p 
Western Digital pvgal, wd90c00, wd90c10, wd90c24, 

Wd90c30, Wd90c31, Wd90c33 
Genoa gvga 

Trident tvga8800cs, tvga8900b, tvga8900c, 

tvga8900cl, tvga9000 
NCR ncr77c22, ncr77c22e 

Cirrus Logic clgd5420, clgd5422, clgd5424, 

Clgd5426, Clgd5428, clgd5429, 
clgd5430, clgd5434, clgd5436, 
clgd6205, clgd6215, clgd6225, 
clgd6235, C16410, C16412, C16420, 
C16440 

RealTek realtek 

ARK ark1000pv, ark1000vl, ark2000pv 

Compaq cpq_avga 
Oak oti067, oti077, oti087 

Avance Logic al2101, ali2301, ali2302, ali2308, 

ali2401 

Chips & Technology «65520, «65530, «65540, «65545 
MX nix 
Video7 video7 
G eneri C generic 
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option "opti onstri ng" Allows the user to select certain optionsprovided by the 

drivers. Currently thefollowing stri ngs are recognized: 
ìegend— For Sigma Legend ET4O00-based boards. This option 
enables a special clock-selection algorithm used on Legend 
boards, and MUST bespecified for these boards tofunction 
correctly. 

swap_hibit— For Western D igital/PVGAl chipsets. Some 
Western D igital-based boards requi re the high-order clock- 
select lead to beinverted. It isnot possi ble for the server to 
determinethisinformation at run-time. If the 9th clock in the 
list of clocks detected by the server is lessthan 30M hz, this 
option likely needsto beset. 

Hibit_iow, hibitjigh— For Tseng ET4000 chipsets. W ith some 
ET4000 cards, the server hasdifficulty getti ng the state of the 
high-order clocks select bit right when started from a high- 
resolution text mode. Theseoptionsallow thecorrect initial 
state ofthat bit to be speci fi ed. To find outwhat thecorrect 
initial state is, start the server from an 80x25 text mode This 
option is only needed if the clocks reported by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 
8ciocks— For the PV GAI chipset, the default is 4 clocks 
Somecardswith this chipset may support8 clocks. Specifying 
thisoption will allow thedriver to detect and usetheextra 
clocks 

i6ciocks— ForT rident tvga8900b and 8900C chipsets. Some 
newer boards usi ng 8900B and 8900C chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boards will 
haveaTCK9002 oncK9004 chip on them. Specifying this option 
will allow the driver to detect and use the extra 8 clocks. 
probe_ciocks— For C irrus chipsets. T he C i rrus driver has a 
fixed set of clocks that are normally used. Specifying this 
option will force the driver to probe for clocks instead of 
reportingthebuilt-in defaults. Thisoption is for debugging 
purposesonly. 

power_saver— Thisoption enables the server to use the power- 
savi ngfeaturesof VESA D PM S-compati ble moni tors. The 
suspend level is currently not supported. Referto the 
xF86Config(4/5) manual pagefordetailsof how to set thetime- 
outs for the different levels of operation. This option is 
experi men tal. 

noaccei— For Cirrusand W D chipsets. Thisoption disables 
theaccelerated features for the cigd5426, cigd5428, wd90c24, 
wd90c3i, and wd90c33 eh i psets. 

fifo_conservative— For C irrus chipsets. This option setsthe 
crtfifo threshold to a conservati ve value for dot clocks above 
65M Hz. Thisreduces performance, but may help in 
eliminating problemswith "streaks" on thescreen during 
BitBLT operati ons 

fifo_aggressive— For C irrus chipsets. Thisoption setsthe 
crt_fifo threshold to an aggressive value for dot clocks above 
65M Hz. This may increase performance. 
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speedup "sei ect i on 



siow_dram— For C irrus chi psets. T his option setstheD RAM 
timingsfor slow D RAM chips. 

fast_dram— For ET4000 and C irrus chi psets. Thisoption sets 
theDRAM timingsfor fast D RAM chips 
no_2mb_banksei— For C irrus eh i psets. T h i s option is required 
for C irrus cardswith 2MB of videoram, which isin theform of 
512kx8 D RAM s(4 chips) rather than 256kx4 D RAM s (16 
chips). 

no_bitbit— For C irrus chi psets Thisoption disablesuse of 
hardwareBitBLT. 

linear— Atterri pt a linear mapping of theframebuffer into 
high memory. C urrently only supported for some C irrus 
confi gurations. 

meddram, f avour_bitblt, sw_cursor, clgd6225__lcd, mmio — M Ore 

Cirrus-specificoptions. Referto /usr/xiiR6/iib/xn/doc/ 
README.cimus for a detai led description of C irrus options. 
Sets the sei ection of speedups to use. The optional selection 
stri n g can take th e f o 1 1 ovvi n g vai ues: 



nospeedup 



ali 

If the sei ection string isomitted, or if thespeedup option is 
omitted, the sei ection defaultsto ali. Some of the SpeedU ps 
can only beused with theET4000, WD90C31, and WD90C33 
chipsetsand othersrequireavirtual resolution with axdimof 
1024. SpeedU ps thatwon't workwith agiven confi guration 
are automati cally disabled. 

D isables the SpeedU p code. T his isequivalent to speedup 



Ramdac r a md a c - 1 y p e T his specifies the type of RAM D AC used on the board. 0 nly 

theARK driver currently usesthis. RAM DAC typesrecognized 
include 

Att20c490-AT&T 20C490 or compatible 8-bit RAM DAC. 
Att20c498-AT&T 20C498 or compatible 16-bit RAM DAC. 
zoomdac— RAM DAC used by the H ercules Stingray Pro/V and 
64/V. 

stgi 700- STG 1700 or compatible RAM DAC. 

N otethat xFree86 has some internai capabilitiesto determi ne what hardware it isrunningon. Thus, normally thekeywords 
chipset, ciocks, and videoram don't haveto be specified. Buttheremay be occasi onswhen this autodetection mechanism 
fails, (for example, too high a load on themachinewhen you start the server). For caseslikethis, you should first run 
xf86_svga on an unloaded machine look at the results of the autodetection (that areprinted out during server startup), and 
then explicitly specify these parameters in theconfiguration file. Itisrecommended that ali parameters, especially clock 
values, be specified in thexF86Config file 



FILES 



<XRoot>/bin/XF86 SVGA 
/etc/XF86Config 
<XRoot>/lib/X1 1 /XF86Conf ig 
<XRoot>/lib/X1 1 /doc/README . ark 
<XRoot>/lib/X1 1 /doc/README .ati 



TheSVGA colorX server 

Server configuration file 

Server configuration file 

Extra documentation for theARK driver 

Extra documentation fortheATI vgawon-der driver 



XF86_VGA16 

<XRoot>/lib/X11 /doc/README. cirrus 
<XRoot>/lib/X11/doc/README.trident 
<XRoot>/lib/X11/doc/README.tseng 
«Root>/lib/X1 1 /doc/README .Oak 
<XRoot>/lib/X1 1 /ddC/README .Video7 
<XRoot>/lib/X1 1 /doc/README .WstDig 

Note: <xRoot> refersto theroot of theXll instali tree 
SEE ALSO 

x(l), Xserver(l), XFree86(l), XF86Conf ig(4/5), xf 86conf ig(l), xvidtune(l), xdm(l), xinit(l) 

BUGS 

Bug reports are welcome, and should bee-mailed to the address listed below. 

CONTACT INFO 

xFree86 source i s avai lable from the FTP serverftp.xFree86.org. 
Send e-mail to xFree86@xFree86.org for details. 

AUTHORS 

Referto thexFree86(l) manual page. 

xFree86 Versi on 3.1.2 

XF86JGA16 

XF86 VGA16— 4-bit nonaccelerated X W indow System server for UNIX on x86 platforms 
SYNOPSIS 

XF86 VGA16 [ : displaynumber] [ option ] ... 

DESCRIPTION 

xf86_vgai6 isa 4-bit color server forvGA cards. The default root visual for this server isstaticcoior. Italso includessupport 
forthenon-VGA monochrome cards described in thexF86_Mono(l) manual page. It may berun in adual-headed configura- 
tion. 

CO NFIGU RATIO NS 

The xf86_vgai 6 server supports the followi ng popular svga chi psets i n 16-color mode. 



ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 

68800-6, 68800AX, 68800LX, 88800CX, 88800GX 

Tseng ET4000 

Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

CirrUS CL6410, CL6412, CL6420, CL6440 

Oak OTI067, OTI077, OTI087 



Additi onally, it supports generic VGA cards. 

xf86_vgai6 does not support the accelerated functionsof thesupported chipsets. 



E xtra d 0 cu m en tati 0 n f 0 r t h e C i rrus d r i ver 

Extra documentation for theTrident driver 

Extra documentation for the ET4000 and ET3000 drivers 

Extra documentation for the Oak driver 

Extra documentation fortheVideo7 driver 

Extra documentation for theWD/PVGA driver 
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OPTIONS 

In additi on to thenormal server options described in thexserver(l) manual page, xf86_vgm6 accepts some more command- 
lineswitches, as described in thexFree86(l) man page. 

SETUP 

xFree86 uses a confi gurati on filecalled xF86Config for i ts i n i ti al setup. 

SeethexF86Config(4/5) man page for general details. Here, only thexF86_vGM6 specific parts are explained. 

The Driver entry in thescreen section of thexFseconfig fileshould beset to vgai6.To run in dual-headed configuration, 
thereshould also beascreen section with the Driver entry setto mono. 

EntriesfortheDevice section in thexFseconfig fi le include the following: 

chipset "dame " Specifies a chipset so the correct driver can be used. Possible 



chipsets are 

ATI vgawonder 

Tseng et4000, et4000w32, et4000w32i, et4000w32p 

Trident tvga8800cs, tvga8900b, tvga8900c, 

tvga8900cl, tvga9000 

CimjS C16410, C16412, C16420, C16440 

Oak oti067, oti077, oti087 

GenericVGA generic 



option 'opti onstri ng" Allows the user to sei ect certai n options provided bythe 

drivers. Currently, thefollowing stringsare recognized: 
ìegend— For Sigma Legend ET4000-based boards. This option 
enables a special clock-selection algorithm used on Legend 
boards, and MUST bespecified for these boards tofunction 
correctly. 

mbit iow, hibitjigh— ForTseng ET4000 chipsets. W ith some 
ET4000 cards, the server hasdifficulty getti ng the state of the 
high-order clocks sei ect bit right when started from a high- 
resolution text mode. These options allow thecorrect initial 
state ofthat bit to be speci fi ed. To find outwhat the correct 
initial state is, start the server from an 80x25 text mode This 
option is only needed if the clocks reported by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 
power_saver— This option enables the server to use the power 
savi ngfeaturesof VESA D PM S-compati ble moni tors. The 
suspend level is currently not supported. 
Referto thexF86Contig(4/5) manual page for details of how to 
set thetime-outsfor the different levelsof operation. This 
option is experi mental. 

N otethat xFree86 has some internai capabilitiesto determi ne what hardware it isrunningon. Thusnormally thekeywords 
chipset, ciocks, and videoram don't haveto be specified. Buttheremay be occasi ons when this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For caseslikethis, you should first run XF86 
vgai6 on an unloaded machine, look at the results of the autodetection (that areprinted out during server startup), and then 
explicitly specify these parameters in the configuration file It isrecommended that ali parameters, especially clock values, be 
specified in thexF86Config file. 



FILES 

<xRoot>/bin/xF86 vgai6 Thel6-colorX server 

/etc/xF86Contig Server configuration file 

<xRoot>/iib/xn/xF86Config Server configuration file 

Note: <xRoot> refersto theroot of the X 11 instali tree. 
SEE ALSO 

x(l), Xserver(l), XFree86(l), XF86Conf ig(4/5), XF86 Mono(l), xf 86conf ig(l), xvidtune(l), xdm(l), xinit(l) 

CONTACT INFO 

xFree86 source is avai lable from the FTP serverftp.xFree86.org. 
Send e-mail to xFree86?xFree86.org for details. 

AUTHORS 

Theprimary developer of th i s server isGertjan Akkerman (akkermanedutiba.twi.tudeift.nl). 
Seealso thexFree86(l) manual page. 

xFree86 Versi on 3.1.2 

xf 86conf ig 

xf86config— Generate an xF86Config file 
SYNOPSIS 

xf86config 

DESCRIPTION 

xf86config isan interacti ve program for generati ngan xF86Configfiieforusewith xFree86 X servers. 
FILES 

<xroot>/iib/xn/cards Video cards database 

SEEALSO 

XFree86(l), XF86Conf ig(4/5), reconfig(l) 

AUTHOR 

H arm H anemaayer 

XFree86 VeTSiOn 3.1.1 

xfd 

xfd — D isplay ali thecharactersin anX font 
SYNOPSIS 

xfd [-options ...] -fn f o n t n a me 
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DESCRIPTION 

Thexfd utility creates a wi ndow contai ni ng the nameof the font being displayed, a row of command buttons, several linesof 
text for displaying character metrics, and a grid containing one glyph per cell. The characters are shown in increasi ng order 
from left to right, top to bottom. The first character displayed at the top left wi II be character number 0 unless the -start 
option hasbeen supplì ed, in which case the character with the number given in the -start option wi 1 1 beused. 

The characters are displayed in a grid of boxes, each largeenough to hold any single character in the font. Each character 
glyph isdrawn usingthepoiyTexti6 request(used by thexiib routine xDrawstringi6). If the-box option isgiven, arectangle 
will bedrawn around each character, showingwherean imageTexti6 request (used by thexiib routinexDrawimagestringi6) 
would cause background colorto bedisplayed. 

Theorigin of each glyph isnormally set so that the character isdrawn in the upper left corner of the grid cell. H owever, if a 
glyph has a negative left hearing or an unusually largeascent, descent, or right hearing (asis the case with cursor font), some 
characters may not appear in their own grid cells. The -center option may beused to force ali glyphsto becentered in their 
respective cells. 

Ali the characters in the font may notfit in the wi ndow at once. To seethenext pageof glyphs, press the N ext button atthe 
top of the wi ndow. To see the previ ous page, press Prev. To exit xtd, press Quit. 

Individuai character metrics (index, width, bearings, ascent, and descent) can bedisplayed at thetop of thewindow by 
clickingon the desi red character. 

The font name displayed at thetop of thewindow is the full nameof the font, as determi ned by the server. Seexisfonts for 
waysto generate listsof fonts, aswell asmoredetailed summariesof their metrics and properties. 

OPTIONS 

xtd acceptsall of the standard toolkit command-li ne opti ons along with thefollowing additional options 

-fn font Thisoption specifies the font to bedisplayed. Thiscan also be 

set with the FontGrid font resource. A font must be specified. 

-box Thisoption indicates that a boxshould bedisplayed outlining 

the area that would be fi I led with background color by an 
imageText request. Thiscan also be set with the FontG rid 

boxChars resource. T he default ÌS False. 

-center Thisoption indicates that each glyph should becentered in its 

grid. Thiscan also be set with the FontG rid centercnars 
resource. The default isFaise. 

-start number T his option specifies the glyph index of the upper left corner 

of thegrid. Thisisused to view characters at arbitrary 
locations in the font. Thiscan also be set with the FontG rid 
startchar resource. The default i s 0. 

-bc color Thisoption specifies the colorto beused if imageText boxes 

aredrawn. Thiscan also be set with the FontGrid boxcoior 
resource. 

-rows numrows T his option specifies the number of rows in the grid. T his can 

also be set with the FontG rid ceiiRows resource 

-coiumns numcol s Thisoption specifies the number of columns in thegrid. T his 

can also be set with theFontG rid ceiicoiumns resource. 



WIDGETS 

In order to specify resources, it isuseful to know the widgets that compose xtd. In the notati on below, indentation indicates 
hierarchical structure. Thewidget class name isgiven first, followed by thewidget instance name. The application class name 
isxtd. 




Xfd xfd 

Paned pane 

Label fontname 
Box box 

Command quit 
Command prev 
Command next 
Label select 
Label metrics 
Label range 
Label start 

Form form 
FontGrid grid 



FONTGRID RESOURCES 

The FontGrid widget isan application-specific widget, and a subclass of the Si mplewidget in theAthena widget set. The 
effectsand instancenamesof thiswidget's resources aregi ven in the"0 ptions" subsection. Capital ize the first letter of the 
resource i nstance name to get the correspondi ng class name. 

APPLICATION SPECIFIC RESOURCES 

The instancenamesof the application-specific resources aregi ven in thefollowing list. Capitalizethefirst letter of the 
resource i nstance name to get the correspondi ng class name. These resources are unii kely to be i nteresti ng unlessyou are 
localizing xfd for a different language. 



selectFormat 



metricsFormat 



rangeFormat 



startFormat 



nocharFormat 



Specifies a printf-style format stri ng used to display informa- 
tion abouttheselected character. The default iscnaracter 
ox%02x%02x (%u,%u) (%#o,%#o). Theargumentsthatwill come 
after the format stri ng are 

char.bytel, char.byte2, char.bytel, char.byte2, char.bytel, 

cnar.byte2. char.bytel is byte 1 of the selected character. 

char.byte2 i s byte 2 of the selected character. 

Specifi es a printf-style format stri ng used to display character 

metriCS. The default iSwidth %d; left %d, right %d; ascent 

%d, descent %d (font %d, %d). T he arguments that wi II come 
after th e f o rm at stri n g are th e eh aracter m etr i cs wi dth , 
Ibearing, rbearing, character ascent, character descent, font 
ascent, and font descent. 

Specifies a printf-style format stri ng used to display the range 
of characterscurrently beingdisplayed. Thedefault isrange: 
ox%02x%02x (%u,%u) tnru 0x%02x%02x (%u ,%u) . T he arguments 
th at w i 1 1 come after the f orm at stri n g are th e f o 1 1 ovvi n g f i el d s 
from thexFontstruct that is returned from opening the font: 

min_byte1, min_char_or_byte2, min_byte1, min_char_or_byte2, 
max_byte1, max_char_or_byte2, max_byte1, max_char_or_byte2. 

Specifies a printf-style format stri ng used to display informa- 
ti on about the character at the upper left corner of the font 
grid. Thedefault is upper left: 0x%04x (%d,%d).The 
arguments that will comeafter theformat stri ng are the new 
character, the high byte of the new character, and the low byte 
of the new character. 

Specifies a printf-style format stri ng to display when the 
selected character doesnot exi st. Thedefault isno sucn 
character 0x%02x%02x (%u,%u) (%#o,%#o. T hearguments that 
will comeafter theformat stri ng arethesameasfor the 

select -Format resource. 
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SEEALSO 

x(l), xisfonts(l), xrdb(l), xfontsei(l), X Logicai Font D escription Conventions 
BUGS 

The program should skip over pagesfull of nonexistent characters. 
AUTHOR 

Jim Fulton (M IT X Consortium); previ ous program of thesamenameby M ark Li Ili bridge (M IT Project Athena) 

X Versi on 11 Re!ease6 

XFree86 

XFree86— X11R6 for U N IX on x86 platforms 
D ESCRIPTION 

xFree86 isa collection of X serversfor U N IX-like 0 Sson Intel x86 platforms. Thiswork isderived from X386m .2, which was 
contri buted to xurs by Snitily Graphics Consulting Service. 

CO NFIGU RATIO NS 

xFree86 operates under the following operati ng systems: 

■ SVR3.2: SCO 3.2.2, 3.2.4, ISC 3.x, 4.x 

■ SVR4.0: ESIX.M icroport, Dell, UHC, Consensys, M ST, ISC, AT&T, NCR 

■ SVR4.2:Consensys,Univel(UNIXWare) 

■ Solaris (x86) 2.1, 2.4 

■ FreeBSD 1.1.5, 2.0, 2.0.5, N etBSD 1.0 (Ì386 port only) 

■ BSD/386 version 1.1 and BSD/OS 2.0 

■ Mach (from CMU) 

■ Linux 

■ Amoeba version 5.1 

■ M inix-386vm version 1.6.25.1 

■ LynxOSAT versions2.2.1 and 2.3 

NETWORK CO NNECTIONS 

xFree86 supports connections made usi ng the following reliable byte-streams: 

Locai xFreese supports locai connectionsviaStreamspipeviavarious 

mechanisms, usingthefollowing paths(n represents the 
display number): 

/dev/X/server.n (SVR3 and SVR4) 

/dev/X/Nserver.n (SVR4) 

/dev/XnS and /dev/XnR (SCO SVR3) 

In SVR4.0.4, iftheAdvanced Compati bility Packageis 
instai led, and in SVR4.2, xFree86 supports locai connections 
from clientsfor SCO XSight/O DT, and (with modifications 
tothebinary) clientsfor ISC SVR3. 
UNIX Domain XFreese uses / tmp/.xn - unix/xn asthefilenameforthesocket, 

wheren is the display number. 
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TCPIP 



xFreese listenson port htonsleeeo+n), wheren isthedisplay 
number. 

Thisis the default communication medium used under native 
Amoeba. NotethatunderAmoeba, the server should be 
started with a h o s t name di spi aynumber argument. 



Amoeba RPC 



ENVIRONMENT VARIABLES 



For operati ng systemsthat support locai connectionsother than UNIX Domain sockets (SVR3 and SVR4), thereisa 
compi led-in list specifying the order in which locai connections should beattempted. This list can beoverridden by the 
xlocal environmentvariabledescribed next. If the display name indicates a best-choice connection should bemade(for 
example, 10.0), each connection mechanism istried until aconnection succeedsorno moremechanismsareavailable. Note: 
FortheseOSs, theU N IX Domain socket connection istreated differently from theother locai connection types. To useit 
the connection must bemadeto unix:0.0. 

The xlocal environment variable should contai n a list of onemoreof the followi ng: 



which represent SVR4 Named Streamspipe, Old-styleUSL Streamspipe, SCO XSight Streams pipe, and ISC Streamspipe, 
respectively. You can select a single mechanism (for example, xlocal=named), or an ordered list, for example, 

XLOCAL=" NAMED : PTS : SCO " 

This variable overrides the compi led-in def aulta For SVR4 it isrecommended that named be the first preference connection. 
T he default setting is 

PTS: NAMED: ISC: SCO. 

To globally overridethecompiled-in defaults, you should define (and export if usi ng sh or ksh) xlocal globally. If you use 
startx/xìnit, the definition should beat the top of your .xinitrc file. If you usexdm, the definitions should beearly on in 

the <XRoot>/lib/X1 1 /xdm/Xsession script. 



In additi on to thenormal server optionsdescribed in thexserver(l) manual page, XFreese accepts the foli ovvi ngcommand- 
lineswitches: 



NAMED 



PTS 



SCO 



ISC 



OPTIONS 



-gamma vai ue 



-probeonly 



-quiet 
-bpp n 



-weight nnn 



xx specifiestheVirtual Terminal device number that XFreese 
will use. Withoutthisoption, xFree86 will pick the first 
available V i rtual Terminal that it can locate. This option 
appliesonlyto SVR3, SVR4, Linux, and BSD OSs with the 
syscons or pcvt driver. 

C auses the server to exit after the device probi ng stage. The 
xF86Contig fileisstill used when thisoption isgiven, so 
information that can beauto detected should becommented 
out. 

Suppresses most informati onal messages at startup. 

Set number of bitsper pixel. The default is 8. Legai valuesare 

8, 15, 16, 24, 32. N ot ali servers support ali values. 

Sets RGB weighting at 16 bpp. The default isses. This applies 

only to those servers that support 16 bpp. 

Sets the gamma correrti on. vai ue must bebetween 0.1 and 10. 

The default isi .0. This valueisapplied equally to theR, G, 

and B values. N ot ali servers support this. 
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-rgamma value 

-ggamma value 

-bgamma value 

-showconf ig 
-verbose 

-xf86config file 
-keeptty 

KEYBOARD 

M ultiple key presses recognized di rectly by xFree86 are 
Ctrl-tAlt-mackspace 

Ctrl-tAlt-tKeypad-Plus 
Ctrl+Alt+Keypad-M inus 
Ctrl-hAlt+Fl... F12 

SETUP 



Setsthered gamma correction. vaiue must bebetween 0.1 and 
10. T he default is 1 .0. Not ali servers support this. 
Sets the green gamma correction. value must bebetween 0.1 
and 10. The default is 1 .0. N ot ali servers support this. 
Sets the blue gamma correction. value mustbe between 0.1 
and 10. The default is 1 .0. N ot ali servers support this. 
Printsout a list of screen drivers confi gured in theserver. 
M aximizesinformation printed at startup (morethan the 
default). 

Reads the server confi guration from file T his option is only 
availablewhen theserver isrun asroot (that is, with real- 
UID 0). 

Prevents the server from detaching itsinitial controlli ng 
terminal. Thisoption isonly useful when debuggingthe 
server. 



Immediately kills the server— no questionsasked. (Can be 
disabled by specifying "Dontzap" in th e Server- Flags section of 

theXF86Config file.) 

Changes video modeto next onespecified in theconfiguration 
file, (increasing video resolution order). 
Changes video modeto previous onespecified in the 
confi guration file, (decreasing video resolution order). 
ForBSD systems usi ng the syscons driver and Linux, these 
keystrokecombinationsareused to switch to Virtual Console 
1 through 12. 



xFreese uses a configuration file cai led xF86Config for itsinitial setup. Referto thexF86Config(4/5) manual page for more 
information. 



FILES 

«Root>/bin/XF86 SVGA 
<XRoot>/bin/XF86 Mono 
<XRoot>/bin/XF86 S3 
<XRoot>/bin/XF86 Mach8 
<XRoot>/bin/XF86 Mach32 
<XRoot>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<XRoot>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Config 

<XRoot>/lib/X1 1 /XF86Conf ig .hostname 
<XRoot>/lib/X1 1 /XF86Conf ig 
<XRoot>/bin/ 



The color SVGA X server 

ThemonochromeX server forVGA and other mono cards 

Theaccelerated S3 X server 

The accelerated Mach8 X server 

Theaccelerated Macn32 X server 

Theaccelerated Mach64 X server 

Theaccelerated P9000 X server 

The accelerated agx X server 

Theaccelerated ET4000/W32 X server 

The accelerated 8514/a X server 

Server configuration file 

Server configuration file 

Server configuration file 

Client binaries 
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<XRoot>/include/ 

<XRoot>/lib/ 

<XRoot>/lib/X11/fonts/ 

<XRoot>/lib/X11/rgb.txt 

<XRoot>/lib/X11/XErrorDB 

<XRoot>/lib/X11/app-defaults/ 

<XRoot>/man/raan?/ 

/etc/Xn.hosts 

Note: <xRoot> refersto the root of the X 11 instali tree. 



H eader files 

Libraries 

Fonts 

Color namesto RGB mapping 
C lient errar message database 
C lient resource speci fi cations 
M anual pages 

Initial access control list for display n 



SEE ALSO 

X(l), Xserver(l), xdm(l), xinit(l), XF86Conf ig(4/5), xf86conf ig(l), XF86 SVGA(l), XF86 VGA16(1), XF86 Mono(l), XF86 Accel(l), 
xvidtune(l) 

AUTHORS 

ForxnR5, XF86 1.2 wasprovided by the following: 

ThomasRodl (roell§inforaatik.tu-muenchen.de; Server and SVR4 Stuff), M ark W . Snitily (mark@sgcs.com sgcs; SVR3 

support, X Consortium Sponsor), and many morepeopleoutthereon theN et who helped with ideasand bugfixes. 
xFree86 was integrated into xi 1R6 by the following team: 

Stuart Anderson (anderson9metroiink.com), DougAnson (dansonWgc.com), G ertjan Akkerman 

(akkerman9dutiba.twi.tudelft.nl), M ikeBemSOn (mike9nibsun.mlb.org), Robin C Utshaw (robin9XFree86 . org), David D awes 
(dawes9XFree86.org), M are E vans (marc9XFree86. org), Pascal H aible (haible9izf m. uni-stuttgart .de), M atthieu H errb 
(Matthieu.Herrb91aas.fr), Dirk Hohndd (hohndel9XFree86.org), David Holland (davidh9use.com), Alan Hourihane 
(alanh9fairlite.demon.co.uk), Jeffrey H SU (hsu9soda.berkeley.edu), Glenn Lai (glenn9cs.utexas.edu), Ted Lemon 
(mellon9ncd.com), Rich M urphey (rich9XFree86.org), H ansN asten (nasten9everyware.se), M ark Snitily (mark9sgcs.com), 
Randy Terbush (randyt9cse.unl.edu), Jon TombS (tombs9XFree86.org), KeSS Verstoep (versto9cs.vu.nl), Paul V ixie 

(paui9vix.com), M ark W eaver (Mark weaver9brown.edu), David Wexelblat (dwex9XFree86.org), Philip W heatley 
(phiiip.wheatiey9Coiumbiasc.NCR.coM), Thomas Wolfram (woif9prz.tu-beriin.de), and 0 rest Z borowski 

(orestz9eskimo.com). 



ThexFree86 enhancement package was provided by 

David Dawes, dawes9XFree86.org 

Glenn Lai, glenn9cs.utexas.edu 

JimTsillas, jtsilla9ccs.neu.edu 
David Wexelblat, dwex9XFree86.org 



D irk H Ohndel, hohndel9XFree86.org 

AmanciO H astyjr., hasty9netcom.com 
Rich M urphey, rich9XFree86.org 



Releasecoordination, administration of FTP repository and 
mailing lists. Sourcetree management and integration, 
accelerated server integration, fixing, and coding. 
TheSpeedU p codefor ET4000-based SVGA cards, and ET4000/ 
W32 accelerated server. 

M any server speedupsfrom thefX386 seriesof enhancements. 
Integration ofthefX386 codeinto the default server, many 
driver fixes, and driver documentati on, assembly of the VGA 
card/monitor database, development of the generi c video 
mode listi ng. Accelerated server integration, fixing, and 
coding. 

Linux-shared libraries and releasecoordination. Accelerated 
server integration and fixing. Generic administriviaand 
documentation. 

Portingto 386BSD version 0.1 and XS3 development. 
Ported to 386BSD version 0.1 based on the originai port by 
Pace W illison. Support for 386BSD, FreeBSD, and NetBSD. 
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Robert Baron, Robert.Baron@ernst.mach.cs.cmu.edu 

OrestZborOWSki, orestz@eskimo.com 

DougAnSOn, danson@lgc.com 

David Holland, davidh@use.com 

David M cCullOugh, davidm@stallion.oz.au 

M ichaeì Rohleder, michael.rohleder@stadt-frankfurt.de 

KeesVerstoep, versto@cs.vu.ni 

M are Evans, Marc@XFree86.org 

Philip H omburg, phiiipecs.vu.nl 
Thomas M ueller, tm@systnx.de 

Jon TombS, tombs@XFree86.org 
H arald Koenig, koenig@tat.physik.uni-tuebingen.de 
Bernhard Bender, br@elsa.mhs.compuserve.com 
Kevin M arti n, martin@cs.unc.edu 

Rik Faith, faith@cs.unc.edu 

Tiago Gons, tiago@comosjn. hobby. ni 

HansNasten, nasten@everyware.se 

MikeBemSOn, mike@mbsun.mlb.org 

M ark W eaver, Mark Weaver@brown.edu 

C raig G roeSChel, craig@metrolink.com 

H enry Worth, Henry.Worth@amail.amdahl.com 

Erik Nygren, nygren@mit.edu 

H arry Langenbacher, harry@brain.jpl.nasa.gov 

ChrisM ason, mason@mail.csh.rit.edu 

H enrik H armsen, harmsen@eritel.se 

Simon Cooper, scooper@vizlab.rutgers.edu 

H arm H anemaayer, hnanemaa@cs . ruu . m 

M i ke T i erney, f loyd@eng .umd.edu 

Bill Conn, conn@bnr.ca 

Brad BoSCh, brad@lachman.com 

Alan H Ourihane, alanh@fairlite.demon.co.uk 

M are La France, Marc.l_a-France@ualberta.ca 

SteveGoldman, sgoldman@encore.com Oak 

J Orge D elgadO, ernar@dit.upm.es 

Bill Conn, conn@bnr.ca 

Paolo Severi n i , lendl@dist.dist.unige.it 

Ching-Tai Chiù, cchiu@netcom.com 

M anfred Brands mb@oceonics.m 
Randy H endry, randy@sgi.com 
Frank D ikker, dikker@cs.utwente.nl 
RegisCridlig, cridlig@dmi.ens.fr 
Jon Block, block@frc.com 



Ported to M ach. 
Ported to Linux. 
Ported to Solaris x86. 
Ported to Solaris x86. 
Ported toSCO SVR3. 
Ported to ISC SVR3. 

Ported to Amoeba based on Leendert van Doorn'soriginal 
Amoeba port of X11R5. 
Ported to OSF/1. 
Ported to M inix-386vm. 
Ported to LynxOS. 

S3 server and accelerated server coordination. 
S3 server development. 
S3 server development. 

Overall work on the base accelerated servers(ATI and 8514/ 
A), and M ach64 server. 

Overall work on the base accelerated serversfATI and 8514/A). 

M ach8 and 8514/A server development. 

M ach8, 8514/A, and S3 server development and BSD/386 

support. 

M ach32 server development. 
M ach32 server development. 
M ach32 server development. 
AGX server. 
P9000 server. 
P9000 server. 
P9000 server. 
P9000 server. 

Cirrus accelerated code(based on work by Bill Reynolds). 

Cirrus accelerated code and ARK driver. 

WD accelerated code. 

WD accelerated code. 

W D 90C 24A support. 

Trident SVGA driver 

ATI vgawonder SVGA driver 

067/077 SVGA driver. 

Oak SVGA driver, and 087 accelerated code. 

WD accelerated code. 

AL2101 SVGA driver. 

Avance Logic ALI SVGA driver. 

C i rrus 64xx SV G A d ri ver. 

Cirrus 6440 support in the cl64xx SVGA driver. 

MX SVGA driver. 

Chips & Technology driver. 

Chips & Technology driver. 
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Chips& Technology driver 
RealTek SVGA driver. 
Video7 SVGA driver. 

16-colorVGA server, and XF86C onfig parser. 
H ercules driver. 

Banked monochromeVGA support, H ercules su pport, and 
mono frame buffer support for dumb monochrome devices. 
and many morepeopleoutthereon theN et who helped with beta-testi ng thisenhancement. 
xFree86 source is avai lablefrom the FTP server ftp.xFree86.org, among others. Send e-mail to xFree86exFree86.org for 
details. 

xFree86 Versi on 3.1.2 



M i ke H olii Ck, hollickUgraphics.cis.upenn.edu 

Peter T ratti er, peter@sbox.tu-graz.ac.at 

C raig Struble, cstruble@acm.vt.edu 

Gertjan Akkerman, akkerman@dutiba.twi.tudelft.nl 

D avor M atic, dmatic@Athena.MIT.EDU 

Pascal Haible, haible@izfm.uni-stuttgart.de 
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xfs— X font server 
SYNOPSIS 

xfs [-conf ig confi gurati on_fi I e] [-port t c p_ po r t ] 

DESCRIVO N 

xfsistheX Window System font server. It supplies fontsto X Window System display servers. 
STARTING THE SERVER 

The server isusually run by a system adm ini strafar, and started via bootfiles like /etc/ re. locai. Users may also wish to start 
private font servers for specific sets of fonts. 

OPTIONS 

-config configuration_fiie Specifiesthe configuration filethefont server will use. 

-is ìisten-socket Specifies a file descriptor that is al ready set up to beused asthe 

li sten socket. Thisoption isonly intended to beused by the 
font server itself when automati cai ly spawning another copy of 
itself to handleadditional connections. 
Specifies theTCP portnumberon which the server will li sten 
for connections. 



T hiscauses the font server to exit cleanly. 
Thissignal isused to cause the server to reread its configura- 
tion file. 

Thissignal isused to cause the server to flush any cached data 
it may have. 

Thissignal isused to cause the server to reset, closing ali active 
connections and rereading the configuration file. 



-port tepport 

SIGNALS 

SIGTERM 
SIGUSR1 

SIGUSR2 

SIGHUP 
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CO NFIGU RATIO N 

Theconfiguration language is a list of keyword and value 
R ecogn i zed keywords i nel ude the fol I ovvi ng: 
catalogue (list of String) 

alternate-servers (list Of String) 

ciient -umit (cardinal) 
cione-seif (Boolean) 

default -point-size 

(cardinal) 

default-resolutions 

(listof resolutions) 



error-file (string) 

port (cardinal) 
use-sysiog (Boolean) 

deferglyphs (string) 



iirs. Each keyword isfollowed by an = and then thedesired value. 



Ordered list of font path element names. Useof the key- word 

"catalogue" isvery misleading at present; thecurrent 

implementation only supports a single catalogue (ali), 

containingall of thespecified fonts. 

List of alternate servers for thisfont server. 

N umber of ci ients thisfont server will support before refusi ng 

servi ce. Thisisuseful fortuningtheload on each individuai 

font server. 

Whether thisfont server should atterri ptto clone itself when it 

reaches the ciient -ìimit. 

Thedefault pointsize(in decipoints) for 

fonts that don't specify. Thedefault is 1 20. 

Resolutionstheserver supports by default. 

Thisinformation may beused asahintfor 

prerendering, and substituted for scaled fonts that do not 

specify a resolution. A resolution isacomma- 

separated pair ofx and y resolutions in pixels 

per inch. M ulti pie resolutions are separated by commas. 

Filmarne of the errar file. AH warningsand errorswill be 

logged here. 

TCP port on which the server will li sten for connections. 
Whether sysiog(3) (on supported systems) isto beused for 
errors. 

Set the mode for delayed fetching and cachingof glyphs. Value 
isnone, meaning deferred glyphs is di sabled, ali, meaning it is 
enabled forali fonts, and 16, meaning it isenabled only for 16- 
bits fonts 



EXAMPLE 

# 

# sample font server conf iguration file 
# 

# allow a max of 10 clients to connect to this font server client-limit = 10 

# when a font server reaches its limit, start up a new one clone-self = on 

# alternate font servers for clients to use alternate-servers = hansen : 71 01 , hansen : 71 02 

# where to look for fonts 

# the first is a set of Speedo outlines, the second is a set of 

# mise bitmaps and the last is a set of 100dpi bitmaps 
# 

catalogue = /usr/X1 1R6/lib/X1 1 /fonts/speedo, 
/usr/X11R6/lib/X11/fonts/misc, 
/usr/X11R6/lib/X11 /fonts/ 100dpi/ 

# in 12 points, decipoints 
default -point -size = 120 

# 100 x 100 and 75 x 75 
default-resolutions = 100,100,75,75 
use-syslog = off 
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FONT SERVER NAMES 

0 ne of the following forms can be used to name a font server that acceptsTC P connections: 

tcp/host name: por t tcp/host nane: por t /cat al oguel i st 

Thehost name specifies the name (or decimai numeric address) of the machine on which the font server isrunning. Theport 
is the deci mal TCP port on which the font server islisteningfor connections. Thecat ai oguei i st specifies a list of catalogue 
names, with + as a separator. 

Examples: tcp/fs.x.org :7100, tcp/1 8. 30. 0.21 2: 71 01 /ali. 

0 ne of the following forms can beused to name a font server that accepts D ECnet connections: 

decnet/nodena me : :f ont$o b j na me decnet/nodena me : :font$obj n a me /catal oguel i st 

Thenodename specifies the name (or decimai numeric address) of the machine on which the font server isrunning. The 
0 b j name isa normal, case-insensitive D ECnet object name. Thecat ai ogueii st specifies a list of catalogue names, with +asa 
separator. 

Examples: DECnet/SRVNOD: : FONTSDEFAULT, decnet/44.70: :f ont$special/symbols. 

SEEALSO 

x(l), font server implementation overview 
BUGS 

M ultiple catalogues should besupported. 
AUTHORS 

DaveLemke(N etwork Computing Devices, Inc.), Keith Packard (M assachusetts Insti tute of Technology) 

X Versi on 11 Re!ease6 
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xhost— Server access control program for X 
SYNOPSIS 

xhost [ [+-]name . . . ] 

DESCRIPTION 

The xhost program isused to add and delete hostnamesor usernamesto the list allowed to make connections to theX server. 
In the case of hosts, this providesa rudimentary form of privacy control and security. It isonly sufficient for a workstation 
(singleuser) environment, although it does limit the worst abuses. Environmentsthat require more sophisticated measures 
should implement theuser-based mediani sm or usethehooksin the protocol for passi ng other authentication datato the 
server. 

OPTIONS 

xhost accepts the foli owingcommand-li ne options. For security, the opti ons that effect access control may only be run from 
the "control li ng host." Forworkstations, this is the same machine as the server. ForX termi nals, it isthelogin host. 

-heip Printsausagemessage. 

[+]name Thegivenname (the plus sign is optional) is added to the list 

allowed to connectto theX server. The name can bea 
hostnameorausername. 
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not hi ng 



NAMES 

A complete name has thesyntaxf a™ 

inet 

dne 

nis 

krb 

locai 



Thegiven name isremoved from the list allowed to connectto 
the server. The name can be a hostname or a username. 
Existing connections are not broken, but new connection 
attempts will bedenied. Notethat the current machine is 
allowed to be removed; however, further connections 
(including attempts to add itback) will not bepermitted. 
Resetting theserver (thereby breaking ali connections) isthe 
only way to allow locai connections again. 
Access is granted to everyone, even if they aren't on the list (in 
otherwords, access control isturned off). 
Access is restri cted to only thoseon the list (that is, access 
control isturned on). 

If no command-linearguments aregiven, a message indicati ng 
whetherornot access control is currently enabled isprinted, 
followed by the list of those allowed to connect. This isthe 
only option that may beused from machinesother than the 
controlli ng host. 



i y :name where the families are as follows: 
Internet host 
DECnethost 

SecureRPC network name 

KerberosV5 principal 

Contains only onename, the empty stri ng 



Thefamily is case insensitive The format of the name vari eswith the fami ly. 

When SecureRPC isbeingused, the network-i ndependent netname(forexample, nis:unix.uid?domainname) can be 
specifi ed, or a locai user can bespecified with just the username and a trai li ngat sign (e) (for example, nis: paté). 

For backward compati bility with pre-R6 xnost, namesthat contai n an at sign areassumed to bein the nis family. Otherwise, 
the inet family isassumed. 

DIAGNOSTICS 

For each name added to the access control list, a line of the form name being added to access control list isprinted. For 
each nameremoved from theaccess control list, a lineof theform name being removed from access control list isprinted. 

FILES 

/etc/X*.hosts 

SEEALSO 

x(l), Xsecurity(l), Xserver(l), xdm(l) 

ENVIRONMENT 

display To get the default host and display to use 



BUGS 



You can't specify a display on thecommand line because -display isavalid command-lineargument (indicatingthatyou 
want to remove themachinenamed display from the access list). 
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TheX server stores network addresses, not h ostri ames. Thisisnotreally abug. If somehowyou changea host's network 
addresswhi le the server is stili running, xhost must beused to add thenew address and/or remove theold address. 

AUTHORS 

Bob Scheifler (M IT Laboratory for Computer Science) andjim Gettys(M IT Project Athena/D EC) 

X Versi on 11 Re!ease6 



xieperf 

xieperf— XIE server extension test and demo program 
SYNTAX 

xieperf [ -option . . . ] 

DESCRIVO N 

The xieperf program isbased upon rs xnperf(l) , and whilenot entirely comprehensivein its coverage of the xie protocol 
(seethe"Bugs" subsection), it isintended to beuseful in theevaluation of xie implementations in theareasof protocol 
adherenceand performance The xieperf program includesteststhat executeeach of the protocol requestsand photoflo 
elements specified by revision 5.0 of the xie protocol. In addition, xieperf providesa set of teste that can beused to vali date 
the detection and transmission of xie protocol request errors, such asFloM atch, FloValue, and so forth. Finally, xieperf 
providesacustomizabledemonstration program for xie. 

A test ismadeup ofthree componente executed in sequence: an initialization function, a test function, and an end function. 
The i nitialization function is responsi ble for allocati ng and populating test resources, such asphotomapsand LUTs, and for 
creati ng a stored photoflo thatwill be executed bythetest function. The test function, in mostcases, simply executesthe 
stored photoflo for a specified number of repetitions. The end function, which iscalled following the test function, isused 
primarily to destroy any noncacheable server resources used by the test, and to free any memory that was dynamically 
allocated by theclient. Some teste, such as -modifyi, -await, -abort, and -redefine, perform additional stepswithin the test 
function innerloop, asrequired bytheelement beingtested, or in an attemptto make the test more visually appealing. 

Evaluating the performance of individuai xie elements isnot assimpleasmeasuring CoreX drawing times. The xie protocol 
requires elements to beembedded within photoflosin orderto beexercised, and the minimum possible photoflo sizeistwo. 
Thisimpliesthat it is impossi ble to measure performance of a single element in i solati on— the ti me ittakesto run the fio 
dependson what other elements exist in the fio. Extrapolating performance of a single element (ortechnique) in a fio must 
bedonecarefully, on acase-by-casebasis, becausein general, measured element performance dependson input imagesize, 
datatype, and other factors, ali of which can beinfluenced by upstream fio elements. N otefurther that the number and type 
of elements in a fio can beinfluenced by the visuals available on the display, so even fio- fio compari sonson machineswith 
different visuals must bedonewith caution. 

M any test labels contai n an abbrevi ated pipeline description. For instance, ip/il/p/ed indicatesimportPhotomap, importLUT, 
Point, and ExportDrawabie. P i pel i nes endi ng in ed (ExportDrawabie) often include hi dden elements such asBandExtract, 
convertToindex, Dither, or Point to match the fio output to thescreen visual. Pi peli nes endi ng in ep (ExportPnotomap) will 
result in a blank window. 

xieperf is compatible with xnperfcomp(l), which isused to compare the outputsof different xieperf andxnperf runsin a 
nice, tabular format. In xieperf you will need to use the -ìabeis option (seethe"Options" subsection), and provide the 
resulting labels fi le to xnperfcomp(l) to obtain correct output. Seethexiiperfcomp(l) man pagesfor moredetailson this. 
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OPTIONS 

xiepertacceptsthefollowingoptions: 

-display hostidpy 
-images <pat h > 



-timeout<s > 



-sync 

-script <f i I e > 



-repeat <n> 



-time <s > 

-depth <dept h> 

-GrayScale 

-PseudoColor 

-StaticGray 

-StaticColor 

-TrueColor 

-DirectColor 

-WMSafe 



Specifies which display to use 
N ormally, xiepert references i mage fi les I ocated in the 
directory images, which xiepert assumes is located in your 
current directory. If the images directory isnot in yourcurrent 
directory, orthefilehasbeen renamed, usethisoption to 
speci fy its location. 

Sometests requi re the reception of an eventsuch asFioNotity 
to continue, and may cause xiepert to hangshould these 
events not bereceived. Thisoption allowstheuserto speci fy a 
timeout value which, if exceeded, will cause xiepert to give 
up waitingfor an event, and conti nueon with the next test in 
sequence. Should an event timeout, awarning messagewill be 
printed to stderr. The default timeout value is 60 seconds. 
Runsthetests in synchronousmode. 
Using thisoption gives the user the abilityto run a subset of 
the available teste and control the number of times the teste are 
executed on an individuai basis. Thisisthoughtto be 
especially useful forthoserunning xiepert fordemonstration 
purposes. Using thisoption causes xiepert to read commands 
specified in a script file, orfrom stdin if <file>is -. Teste are 
specified by newlineterminated input linesof theform 

command [-reps n ] [ -repeat m ] . C haracteTS followi ng and 

includi ng # aretreated ascomments. Seethe -mkscript option. 
Repeats each test n times (by default each test is run two 
times). Thisoption may beused in script fi les also, in which 
case the script file - repeat overridesthecommand-lineoption. 
Specifies how long in seconds each test should be run (default 
5 seconds). 

Useavisual with <depth>planesper pixel (default isthe 
default visual). 

U se a GrayScale visual (default isthe default visual). 

U se a Pseudocolor visual (default i s the default vi sual). 

Use a StaticGray visual (default isthe default visual). 

Use a staticcoior visual (default isthedefault visual). 

Use a Truecoior visual (default isthedefault visual). 

Use a Directcoior visual (default isthedefault visual). 

If xiepert must berun in awindow manager environment, use 

thisflagto makexiepert awareof this. If specified, xiepert 

will create awindow, identical to thesizeof therootwindow, 

and ali furtherwindowscreated by xiepert will betransient 

pop-up children of thiswindow. If thisflag isomitted, xiepert 

will Settheoverride_redirect attributeof ali windOWStO True 

and will also do evi I thingssuch as calli ngxmstaiicoiormap. 
Using this option will cause the window manager to (hope 
fui I y) obey window geometry hi nts specified by xiepert. 
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D isplay a comprehensive list of techniques, by category, 
indicating which of the techniques are supportai by thexiE 
server. 

P ri nt test label to screen priorto callingany of the test code. 
T hisallows the user to know which test isexecuting in case the 
test hangsforsomereason. 

Be verbose when runningevent and errar tests. Also, can be 
used to catch and display informati on on any signals received 
during execution of xiepert. N otethat thisflag is best used in 
a debugging situati on, or to vali date that the error events 
received by xiepert are valid thefirst timethe tests are 
executed on a new platform. 
Run tests that test for event generation. 
Run tests that test for error event generation. 
Skip test calibrati on. This may be used when running xiepert 
in situati onswhere execution timing isnotimportant. 
Execution ti mes wi II not bereported by xiepert when this 
option isenabled.Theinnerlooprepeatcount, additi onally, is 
setto avalueof 5 (but can beoverridden by the -reps option). 
Runsall tests. Thismaytakeawhile, dependingon thespeed 
of your machine and its floati ng-poi nt capabilities. This 
option isignored if a seri pt file is used. 
G enerate a list of the avai lable tests for the xiepert program. 
In xnpert, this list isnormally displayed in theusage 
statement. Itwasyanked from theusageof xiepert becauseit 
wastoo lengthy. 

G enerate a seri pt fi le suitable for use with the seri pt option. I f 
■repeat or -reps arealso specified, they will beautomatically 
placed attheend of each command in the seri pt. Thescript is 
generated to stderr. Seethe -script command, above. 
M osttest flosutilizea photomap resourcefor asource. A 
photomap cacheof up to n entri es is controlied by xiepert to 
avoid having to constantly reload theseimages during test 
i ni tializati on. The default cache size ÌS4. If a value less than the 
default is specified, the cache size will beset to the default. 
G enerates just the descri pti ve labels for each test specifi ed. U se 
-ali or -range to specify which tests are i ncluded. See 
xnpertcomp(l) for more details. 

Pretend we are running xiepert whileconnected to a Dis-only 
capableimplementation of xie. T hiswill cause xiepert to 
executeth ose tests that only use protocol requests round in the 
dis subset of xie, and bypass those which arenotDis- 
compatible. If xiepert detectsaDis server, it will do this 
automati cai ly, and this option isignored. Use -ali or -range to 
specify the initial range of tests. 
Runsall the tests starti ng from the specified nametestl until 
thenametest2, including both the specified tests. Sometests, 
liketheevent and errortests, also requirethe -errors or - 
events optionsto specified. Thisoption isignored if a script is 
used. 
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-reps <n> 



-ImportObscuredEvent 
through -ExportAvailable 



Fixtheinner loop repeti tions to n. This indicate how many 
timesthephotoflo will beexecuted each timethetest isrun. 
Thisoption isoverridden on a per test basisif specified in a 
script. Typi cai ly, xieperf determinesthe ideal numberof reps 
duri ng each test's calibration peri od. 
Test generation of events. Requires -events flag. 



-Badvaiue through 

-FloValueError 



Test generation of errors. Requires -errors flag. 



-ColorList 
-LUT 

-Photomap 
-ROI 

-Photospace 

-Photof lo 

-QueryPhotomap 

-QueryColorList 

-QueryTechniquesDef ault 

through -QueryTechniques 

WhiteAdjust 

-QueryPhotof lo 

-PurgeColorList 

-Abort 



-Await 



-importclientlutl 
-importclientphotol through 
-importclientphoto9 

-importclientroil 
-importclientroi2 
-encodephotol through 
-encodeptioto14 



Createanddestroy coiorList resourcetest. 
C reate and destroy lut resource test. 
C reate and destroy Photomap resource test. 
C reate and destroy roi resource test. 
C reate and destroy Photospace test. 
C reate and destroy Photof io test. 
Q uery Photomap resource test. 
Query coiorList resourcetest. 
Q uery techniques as specified by test name. 



Query Photof io test. 
Purge CoiorList test. 

T h i s test creates a photoflo that isstarted and blocksfor data 
provided by PutcìientDatao. Instead of sending the data, the 
test usesxieAborto to stop the photoflo, and then waitsfor 
the Photof ìoDone eventto besent by the server. If the test times 
out waitingfortheevent, an errormessageissentto stderr. 
T his test creates a fio oftheform importcìientLUT -> 
ExportLUT, and starts the fio executing. xieperf then forks, and 
thechild processstreamstheLUT datato theflo using 
putcìientData, while the parent blocksin xieAwait. If theflo 
successfully finishes, xieAwait will return and theflo state, after 
query, will indicate that it hascompleted. If xieAwait does not 
complete naturally, or after return from xieAwait theflo is stili 
active, an errar is reported to stderr. N ote, on a really slow 
machine, it is possi blethat xieAwait will return before theflo 
has a chance to finish. In thiscase, use the - timeout option to 
i n c rease thetimeout for thistest. 

ImportClientLUT -> ExportLUT test. 

FlOSOf the form ImportClient- Photo -> ExportPhotomap USing 

various decode techniques, for example, G32D, tiff2, 

UncompressedTriple. 

importcìientRoi with 10 rectangles. 
importcìientRoi with 100 rectangles. 

FlOSOf theform ImportPhotomap - ExportPhotomap USing 

various encode techniques, for example G32D, tiff2, 
UncompressedTriple. Originai encoding isshown in left 
window; image after encoding isshown in rightwindow. 



-encodeclientphotol through 
-encodeclientphotol 1 



-exportclientlutl 
-exportclientroil 



-exportclientroi2 
-exportclienthistograml 

through 

-exportclienthistogram4 
-exportclienthistogramroil 

through 

-exportclienthistogramroi4 
-exportclienthistogramcplanel 

through 

-exportclienthistogramcplane4 

-importlutl 

-importphotol 

-importphoto2 
-importroil 

-importroi2 

-importdrawablel 

-importdrawable2 

-importdrawable3 

-importdrawable4 

-importdrawable5 

-importdrawable6 

-importdrawable7 

-importdrawable8 

-constrain! 
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TWO flOS, oneof theform ImportPhotomap -> 

ExportcìientPhoto, and the other of the form 

ImportClientPhoto -> ExportPhotomap, where 

ExportcìientPhoto in thefirstflo usesvarious encode 
techniques, for exampleG32D, tiff2, uncompressedTripie. The 
image before encoding isdisplayed in theleftwindow, while 
therightwindow shows the image thatwasencoded in the 
fi rst fio and read back i n the second fio. 
ExportcìientLUT test. LUT is displayed in a histogram window. 
ExportcìientRoi test, 10 RO Is. T he RO I sthat are sent to the 
server are represented by thefilled rectangles. The RO Isthat 
are received back from the server by the eli ent are drawn as 
white-bordered, nonfilled rectangles. The resulting output 
illustrateshow the server combined the rectangles sent to it. 
Sameas exportclientroil, except using 100 rectangles. 
ExportcìientHistogram tests using various i mages. T he 
histogram isdisplayed in awindowthatoverlapstheimage. 

Same as the ExportcìientHistogram test, but using a RO I 
to i denti fy the area of interest. 

Same as the ExportcìientHistogram test, but usi ng a 
control pianeta identify the area of interest. 

Test importLUT dement; LUT size is 256. 

ImportPhotomap -> ExportPhotomap, with SOUrce and destina- 
ti on equal. 

ImportPhotomap -> ExportDrawable, WÌ ndOW desti nation. 

importRoi -> ExportROi, 10 rectangles, sourceand desti nation 
ROlsequal. 

importRoi -> ExportROi, 100 rectangles, sourceand destination 
ROlsequal. 

ImportDrawable -> ExportDrawable, SOUrce ÌS pixmap, 

destination iswindow. 

ImportDrawable -> ExportDrawable, SOUrce and destination are 

both window. 

ImportDrawable -> ExportDrawable, destination window 

obscured by source window. 

ImportDrawable -> ExportDrawable, SOUrcewindOW Obscured 

by destination window. 

ImportDrawablePlane -> ExportDrawablePlane, pixmap, SOUrce 

= desti nati on. 

ImportDrawablePlane -> ExportDrawablePlane, WÌ ndOW, SOUrce 

= desti nati on. 

ImportDrawablePlane -> ExportDrawablePlane, WÌ ndOW, SOUrce 

obscures desti nation. 

ImportDrawablePlane -> ExportDrawablePlane, WÌ ndOW, 

destination obscures source. 

Constrain Hardciip techniquetest, drawabl e destination. 
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-constrain2 

-constrainphotol 

-constrainphoto2 

-convolvel 

-convolve2 

-convolve3 

-convolve4 

-convolveroil 

-convolveroi2 

-convolvecplanel 

-convolvecplane2 

-mathl through -mathcplane7 

-arithmeticdyadid through 

-arithmeticdyadicS 
-arithmeticmonadid through 

-arithmeticmonadic9 
-arithmeticdyadicroil 

through 

arithmeticdyadicroi5 
-arithmeticmonadicroil 

through 

-arithmeticmonadicroi9 
-arithmeticdyadiccplanel 

through 

-arithmeticdyadiccplane5 
-arithmeticmonadiccplanel 

through 

-arithmeticmonadiccplane9 
-arithmeticf loatdyadid 

though 

-arithmeticf IoatdyadicS 
-arithmeticf loatmonadid 

though 

-arithmeticf loatmonadic9 
-arithmeticroif loatdyadid 

to 

-arithmeticroif IoatdyadicS 
-arithmeticroif loatmonadid 

to 

-rithmeticroif loatmonadic9 
-bandi 



Constrain ciipscaietechniquetest, drawable desti nation. 
Constrain Hardciip techniquetest, photomap destination. 
Constrain ciipscaie techniquetest, photomap destination. 
Boxcar 3x3 convolution test. Smoothing or lowpassfilter. 
Boxcar 5x5 convolution test. Smoothing or lowpassfilter. 
LaPlacian 3x3 convolution test. Edgeor high pass fi Iter. 
LaPlacian 5x5 convolution test. Edgeor high pass fi Iter. 
LaPlacian 3x3 convolution test, with ROI. 
LaPlacian 5x5 convolution test, with ROI. 
LaPlacian 3x3 convolution test, with control piane 
LaPlacian 5x5 convolution test, with control piane 
Variousteststhat exercise the matti element, some tests usi ng 
ROlsand control planes. 
Arithmetic element tests, usingphotomaps 
as the operanda 

Arithmetic element tests, photomap and Constant operands. 

Arithmetic element tests, using - photomaps asthe 
operands, with RO Is. 

Arithmetic element tests, photomap and 
Constant operands, with RO Is. 

Arithmetic element tests, usi ng photomaps as the 
operands, with control planes. 

Arithmetic element tests, photomap and Constant 
operands, with control planes. 

Arithmetic element tests, usingphotomaps 
asthe operands, unconstrained. 

Arithmetic element tests, photomap and Constant 
operands, unconstrained. 

Arithmetic element tests, photomaps asthe 
operands, rois, unconstrained. 

Arithmetic element tests, photomap and 
Constant operands, ROls, unconstrained. 

Bandseiect element test. Imageinput istripleband. If visual of 
xieperf window is a color visual, then th ree Band -seiect 
elementsareused to extract the individuai bands; they are 
combined onceagain using Bandcombine, and displayed using 
convertToindex. If the visual is not color, for example, 
Grayscaie or staticGray, then the fio simply usesone 
Bandseiect element to extract a single band for display. 



-band2 



-band3 
-band4 

-band5 

-comparedyadid through 
-comparedyadic6 
-comparemonadid through 
-comparemonadic6 
-compareroidyadid through 
-compareroidyadic6 
-compareroimonadid through 
compare compareroimonadic6 
-comparecplanedyadid 

through 

-comparecplanedyadic6 
-comparecplanemonadid 

through 

-comparecplanemonadic6 
-matchhistograml 

through 

-matchhistograml 8 
-matchhistogramroil 

through 

-matchhistogramroi6 
-matchhistogramcplanel 

through 

-matchhistogramcplanee 
-unconstrainl 

-pasteupl through -pasteup2 

-geometryl through 

-geometry14 

-geometry15 through 

-geometry28 

-geometry29 through 

-geometry42 

-geomg31dscale1 through 
-geometryf axradid 
-ditherl 
-dither2 



XÌe P fff 

Bandcombine test. Input bands are made of three separate single 
band photomaps. Theseare combined using a Bandcombine 
element, which isfollowed by aBandExtract and 

ExportDrawable. CCIR 601-1 COefficientS. 

BandExtract test. Input is a triple band photomap. CCIR 
601-1 coefficients. Destination window colormap isgray ramp. 
BandExtract test. Input is a triple band photomap. CCIR 
601-1 coefficients. Destination window colormap ìsrgb best 
map standard colormap. 

BandExtract test. Input is a triple band photomap. CCIR 
601-1 coefficients. Destination window colormap is 
rgb_default_map standard colormap. 
Test vari ous compare operatorswith dyadic 
photomap operands. 

Test vari ous compare operatorswith photomap, 
Constant operands. 

Test vari ous compare operatorswith dyadic photomap 

operands, using ROls. 

Test vari ous operatorswith photomap, 

Constant operands, using ROls. 

T est vari ous compare operators with dyadi c 

photomap operands, control planes. 

Test vari ous compare operatorswith photomap, 
Constant operands, control planes. 

MatchHistogram element tests, using vari ous 
imagesand histogram matchingtechniques. 

A selection of MatchHistogram element 
tests, with ROls. 

A selection of M atchH istogram element 
tests, with control planes. 

ImportPhotomap, Unconstrain, Constrain(ClipScale), 
ExportDrawable test. 

Pasteup element tests. 

Geometry element tests, including rotations, scales, 
and mirroring. NearestNeighbor technique. 
Geometry element tests, including rotations, scales, 
and mirroring. AntiAiias technique. 
Geometry element tests, including rotations, scales, 
and mirroring. Biiinearmterpoiation technique. 
Teststo exercisethevariousFAX decodersand 
the Geometry element. 

Dithertest, ErrorDif f usion dither technique, ExportDrawable. 

Dither test, ErrorDif f usion dither technique, 

ExportDrawablePlane. 
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-dither3 
-dither4 
-ditherS 
-dither6 
-dither7 
-dither8 

-logicalmonadid through 
-logicalmonadic16 
-logicaldyadid through 
-logicaldyadic16 
-logicalmonadicroil through 
-logicalmonadicroi16 
-logicaldyadicroil through 
-logicaldyadicroi16 
-logicalmonadiccplanel 

through 

-logicalmonadiccplanel 6 
-logicaldyadiccplanel 

through 

-logicaldyadiccplanel 6 
-blendl 

-blend2 
-blendroil 

-blendroi2 

-blendcplanel 

-blendcplane2 

-blendalphal 

-blendalpha2 
-blendalpharoil 

-blendalpharoi2 

-tripiepointi through 

-triplepoint2 
-funnyencodel through 
-f unnyencode8 



Dithertest, 0rdered(4) dither technique, ExportDrawable. 
Dithertest, 0rdered(4) dither technique, ExportDrawablePlane. 
Dithertest, 0rdered(8) dither technique, ExportDrawable. 
Dithertest, Ordered(8) dither technique, ExportDrawablePlane. 
Dither test, D efault dither technique ExportDrawable. 
Dither test, D efault dither technique ExportDrawablePlane. 

Logicai element, photomap and a Constant 

of 0 as operands, various operators 

Logicai element tests, dyadic photomapsas 

operands, various operators. 

Logicai element, photomap and Constant of 

0 operands, various operators, ROls. 

Logicai element, dyadic photomapsas operands, various 

operators, ROls. 

Logicai element, photomap and Constant of 0 
operands, various operators, Control Planes. 

Logicai element, dyadic photomapsas operands, 
various operators, control planes. 

Biend element test. M onadic source, 0.1 source Constant. 
Alpha Constant of 0.5. 

Biend element test. D yadic sources. Alpha Constant of 0.5. 
Biend test. M onadic source, 0.1 source Constant. Alpha 
Constant of 0.5. ROls. 

Biend element test. D yadic sources. Alpha Constant of 0.5. 
UsesROIs. 

Biend test. M onadic source, 0.1 source Constant. Alpha 
Constant of 0.5. control piane. 
Biend element test. D yadic sources. Alpha Constant of 0.5. 
control piane. 

Biend test. M onadic source, 220 source Constant. Alpha piane 
is a photomap. 

Biend test. D yadic sources. Alpha piane is a Constant 220. 
Biend test. M onadic source, 220 source Constant. Alpha piane 
photomap. ROls. 

Biend test. D yadic sources. Alpha piane is a Constant 220. 
ROls. 

Il lustrate use of point and standard colormaps 
for rendering triple band images. 

These tests are desi gned to perform limited exercisingof XIE's 
capabi lity of deali ng with various encodings of fio source data. 
T he test mu function obtains a photomap usi ng icp -> ep.A 
seriesof independent permanent fio pairs, oneof theform ip 
-> ep, and the otherof the basic form ip -> ed, arecon- 
structed. The encoding parametersfortheExportPnotomap (ep) 
element in the first fio arederived from test configurati on. The 
number of fio pairscreated isalso dependent upon test 
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configuration. T hetests can beconfigured so that the test init 

function will constrain the input photomap to a speci fi ed 

number of levels, on a per band basis, so that word-si zed and 

quad-sized pixels are passed through theflos. Sometests below 

take advantage of this. Seetests.cfortest configuration, and 

hintson how to add similar tests 

Simplepoint element tests. D rawable desti nation. 

Simple Point element test that uses RO I s. D rawabledestination. 

Simple Point element test that uses a control piane. D rawable 

desti nation. 

Simplepoint element test. Photomap desti nation. 
Simple Point element test that uses RO Is. Photomap 
desti nation. 

Simple Point element test that uses a control piane. Photomap 
desti nati on. 

Two flographsarecreated that are the same in structure, 
except for the x and y offsets speci fi ed for the ExportDrawabie 
fio elements. The test init function createsa photoflo based 
upon oneof the two flographs. Theinner loop of the test 
function usesxieRedefinePnotofioo to alternate between each 
of the flographs. M akesurethatyour inner loop reps are2 or 
greaterin orderto exercisethistest fully (see -reps). 
Test xieModifyPnotofioo by adj usti ng RO I offsets and si ze. 
Test xieModifyPnotofioo by changi ng the LUT inputto a 
point element. 

Test xieModif yPnotofio( ) by changi ng ExportDrawabie x and y 
offsets. 

T his test creates a rather long fio of arithmetic elements, each 
of which does nothing morethan add 1 to asmall image. The 
test init function scalesthe input photomap. The 
ExportDrawabie x and y offset is modified randomly during 
each iteration of the test function inner loop. 
This test createsa rather long fio of arithmetic elements, each 
of which does nothing morethan add 1 to a large image. Each 
rep, theGeometry and ExportDrawabie elements at the end of 
the fio are modified to crop a small piece of the input into its 
appropriate place in the larger image. 
These tests ali basi cai ly take an uncompressedTripie image as 
input, send itto convertFromRGB, which co nverts the image to 
someconfigured colorspace, and then send theconverted 
image on to convertToRGB priorto display. T he origi nal image 
isdisplayed in the left-hand window, and theimagethat has 
passed through theflo isshown in theright-hand window. 

Thegoal Of these test ÌStO Show that ConvertFromRGB -> 
ConvertToRGB islOSSleSS. 
ConvertToIndex test, TripleBand BandByPixel. 
ConvertToIndex test, TripleBand BandByPlane. 
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-convertf romindex 



-complex 



The test init function usesaflo contai ni ngconvertToindex to 
display an imagein the leftwindow. The test function uses 
thisdrawableas input to a fio that does convertFromindex -> 
convertToindex and sends the resulti ng i magete theright 
window. Theresultshould belossless. 
A somewhat large fio that uses control planes, LUTs, Point, 

PasteUp, Logicai, Constrain, Dither, Geometry, MatchHistogram, 

Bandcombine, and Bandseiect dements. See the Postscript file 
compiex.ps for a renditi on of thephotoflo that isexecuted. 



XDEFAULTS 

TherearenoX defaultsused bythis program. 

SEEALSO 

x(l), x11perf(l), x11perfcomp(l) 

BUGS 

Thereshould bean images environmentvariableto augmentthe -images option. 

M any tests only scratch the surface of possi ble test cases. Some of the opti ons available for certai n f lo elements are either 
inadequately tested, or ignored altogether. There are insufficient tests for bi tonai, large pixel, or tri pie band tests. 

Some of the test namesareinconsistently cased, for example, -Abort and -ditnen. 

Sometestsarehopelessly slowwhen run against machineswith slow FPUs 

Bitonal images are, forthemost part, displayed usingtheExportDrawabie fio element; however, ExportDrawabiePiane would 
bea better choice. 

AUTHOR 

Syd Logan (AG E Logic, Inc.) 

X Versi on 11 Re!ease6 



ximtoppm 

ximtoppm— Convert an xiiu fileinto aportablepixmap 
SYNOPSIS 

ximtoppm [ x i mf ile] 

D ESC RIPTIO N 

Readsan xim fi le as input. Producesa portable pixmap as output. Thexim toolkit isincluded in thecontrib treeof the 
X.VllR4release 

SEEALSO 

ppm(5) 

AUTHOR 

Copyright (c) 1991 byjef Poskanzer. 



25 M arch 1990 
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xinetd 

xinetd— The extended Internet servicesdaemon 
SYNOPSIS 

xinetd [opt i ons ] 

DESCRIPTION 

xinetd performs the same function asinetd: it starts programsthat provide Internet services. Instead of having such servers 
started at system initialization ti me and bedormant until a connection request arrives, xinetd istheonly daemon process 
started and it listenson ali servi ce portsfor the services listed in itsconfiguration file. When a request comesin, xinetd starts 
the appropriate server. Becauseof theway it operates, xinetd (asweil asinetd) isalso referred to as a super-server. 

The services listed in xinetd'sconfiguration filecan beseparated into two groups. Services in the first group are cali ed 
multithreaded and they requiretheforking of a new server process f or each new connection request. Thenew server then 
handlesthat connection. F or such services, xinetd keepslisteningfor new requests so that it can spawn new servers. On the 
other hand, thesecond group includes services forwhich the servi ce daemon is responsi blefor handling ali new connection 
requests. Such servi cesare cali ed single-threaded and xinetd will stop handling new requests forthem until the server dies 
Services in this group are usually datagram based. 

So far, theonly reason for the existenceof a super-server wasto conserve system resourcesby avoidingto fork a lotof 
processeswho might be dormant for most of their I ifeti me. W hi le fulfil li ng this function, xinetd takes advantage of the idea 
of a su per- server to provi de features such as access control and logging. Furthermore, xinetd isnot limited to services listed in 
/etc/services.Therefore, anybody can use xinetd to start speci al-purpose servers 



OPTIONS 



-d 



-syslog sysl ogfaci I i ty 



-f ilelog I ogf i I e 

-f config_file 
-pid 

-loop rate 



E nables debug mode. This produces a lot of debugging 
output, and it makes it possi bleto useadebugger on xinetd. 
Thisoption enables sysiog logging of xinetd-produced 
messagesusingthespecified sysiog facility. Thefollowing 
facili ty namesaresupported: daemon, auth, user, iocai[o-7] 
(check sysiog. conf(5) fortheir meanings). Thisoption is 
ineffective in debug mode because ali relevant messagesare 
sentto the terminal. 

xinetd-produced messageswill beplaced in thespecified file 
M essagesarealwaysappended to the fi le If the file does not 
exist, itwill becreated. Thisoption is ineffective in debug 
mode because ali relevant messagesare sentto the terminal. 
D etermi nes the fi le that xinetd uses for confi gurati on. T he 

default is/etc/xinetd.conf . 

Theprocesspid iswritten to standard errar. Thisoption is 
ineffective in debug mode 

Thisoption sets the loop rate beyond which aserviceis 
considered in errar and isdeactivated. The loop rateis 
speci fi ed in terms of the number of servers per second that can 
beforked fora process. The speed of yourmachinedetermines 
the correctvalue for thisoption. The default rateis 10. 
If thisoption isused, xinetd will setthesocketoption 
so_reuseaddr before binding the servi ce socket to an Internet 
address. This allows binding of theaddress even if thereare 
programsthat use it, which happenswhen a previous instance 
of xinetd has started some servers that are stili running. This 
option has no effect on RPC services. 
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-ìimit p r o c _ i i mi t Thisoption places a limit on the number of concurrently 

running processe that cari bestarted by xinetd. Itspurposeis 
to prevent processtableoverflows. 

-ìogprocs limit This option places a limit on the number of concurrently 

ru n n i n g servers f o r rem o te u ser I D acq u i si ti o n . 

-shutdownprocs i mi t Thisoption places a limit on the number of concurrently 

running servers for servi ce shutdown (forked when theREcoRD 
option isused). 

Thesysiog and meiog opti ons are mutuai ly exclusive. If noneisspecified, the default issysiog using thedaemon faci I i ty. 
Youshould not confuse xìnetd messageswith messages related to servicelogging. Thelatter arelogged only if thisisspecified 
viatheconfiguration file. 

CO NFIGU RATIO N FILE 

The confi guration file determi nes the servi ces provi ded by xinetd. Any linewhosefirst nonwhitespacecharacter is a # is 
considered a comment line. Empty linesareignored. 

The fi le contai nsentriesof theform: 

service <service_name> 
{ 

<attribute> <assign_op><value><value> ... 
} 

The assi gnment operator, assign_op, can beone of =, +=, -=. T he majority of attributessupport only the si mpleassignment 
operator, =. Attri buteswhosevalueis a set ofvalues supportali assignment operators. For such attributes, += meansadding a 
valueto the set and -= means removi ng a valuefrom the set. A list of these attri butes isgiven after ali the attributes are 
described. 

Each entry defi nes a service i denti fi ed by the service_name. The foli ovvi ng is a list of available attri butes: 

id Thisattribute isused to uniquely identify a service. This is 

useful becausethereexist services that can usedifferent 
protocolsand need to be described with different entriesin the 
confi guration file. By default, theserviceid isthesameasthe 
servi cenarne. 

type Possiblevaluesarethefollowing: 

rpc If this is an rpc service 

internal If this is a service provided by xinetd. 

UNLISTED If thiS ÌS a Service not liSted in /etc/services. 

tiags Possibletiag valuesare 

reuse Set the so_reuseaddr flag on the service socket. 

intercept Intercept packets or accepted connections in 
order to verify that they are coming from 
acceptable locations (internai or multithreaded 
services cannot be intercepted). 
noretry Avoid retry attem pts i n case offork fai Iure, 
socket type Possible values are 

stream Stream-based service 
dgram D atagram-based servi ce 

raw Servi ce that requi res di rect access to I P 

seqpacket Servi cethat requi res rei iable sequenti al 
datagram transmission 
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D etermi nes the protocol that isemployed by the servi ce The 
protocol mustexistin /etc/protocois. If thisattributeisnot 
defined, the default protocol employed by the service will be 
used. 

T his attribute determi nes if the service is si ngle-threaded or 
multithreaded. If its value isyes, the servi ce issi ngle-threaded; 
thismeans that xinetd will start the server and then it will stop 
handling requestsfor the servi ce unti I the server dies. If the 
attri bute vai ue i s no, the servi ce is multi th readed and xinetd 
will keep handling new service requests. 
Determi nes the uid for the server process. The username must 
exi st i n / et c / pas swd . T h i s attri bute i s i n eff erti ve i f th e eff erti ve 
user ID of xinetd isnot super-user. 
D etermi nes the gid for the server process. The group name 
must exist in /etc/group. If a group isnot specified, the group 
of user will beused (from /etc/passwd). Thisattributeis 
ineffectiveif the eff erti ve user ID of xinetd isnot super-user. 
D etermi nes the number of servers that can be si multaneously 
activefor a service. Bydefault, thereisno limit. The value of 
this attri bute can beeither a number or unlimited, which 
means that thereisno limit. 
Determi nes the program to execute for this servi ce. 
Determi nes the arguments passed to the server. In contrastto 
inetd, the server nameshould not beincluded in server_args. 
D eterni i n es th e rem ote h osts to wh i eh th e parti cu I ar servi ce i s 
available. I ts value is a list of IP addresses that can be specified 
in any combinati on of thefollowingways: 

a) A numeric addressin theform of %d .%d M M. If the 
rightmostcomponentsarea, they aretreated aswildcards 
(forexample, 128. 138.12. a matchesall hostson the 
128.138.12 subnet). a. 0.0.0 matchesall Internet addresses. 

b) A factorized addressin theform of %d m m .{%d ,%d ,...}. 
Thereisno need forali four components 

(%d .%d .{%d ,%d , .. .%d} isalso OK). H owever, thefactorized 
part must be at the end of the address. 

c) A network name (from /etc/networks). 

d) A hostname. Ali IP addresses of the specified hostnamewill 
beused. 

Specifying this attri bute without a value makes the service 
available to nobody. 

D eterni i n es th e rem ote h osts to wh i eh th e parti cu I ar servi ce i s 
unavai lable. Its value can be specified in thesameway asthe 
valueof the only from attribute. Thesetwo attri butes 
determinethe location access control enforced by xinetd. If 
noneof thetwo i s specified foraservice, th e servi ce is available 
to anyone. If both are specified foraservice, the one that isthe 
better match for the address of the remote host determi nes if 
th e servi ce i s avai I abl e to that host (for example, if the only 
from list contai ns 128. 138. 209.0 and the no access list contai ns 
128.138.209.10, then the host with theaddress 128.138.209.10 
can not access the service). 
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access times 



logtype 



log_on_success 



log_on_f ailure 



SYSLOG syslog 
f acility 
[syslog level] 



FILE file 
[soft_limit 
[hard_limit] ] 



D etermi nes the ti me intervalswhen the service is available. An 
interval hastheform hour : mi n- hour : mi n (connectionswill be 
accepted atthebounds of an interval). H ourscan rangefrom 0 
to 23 and minutesfrom 0 to 59. 

D etermi nes where the service log output is sent. T here are two 
formats: 

The log output issentto syslog at 
the specified faci I ity. If a level 
is present, the messageswill be recorded at 
that level instead of log_info (which isthe 
default level). 

The log output isappended taf i i e, 
which will becreated if itdoes 
not exist. Two limitson thesizeof the log 
filecan beoptionally specified. Thefirst 
limit is a soft one; xinetd will Ioga message 
thefirst timethislimit isexceeded (if xinetd 
logsto sysiog, the message will besentat 
the log_alert priori ty level). The second 
limit isa hard limit; xinetd will stop logging 
for the affected service (if the log fi le isa 
common log file then morethan one service 
may be affected) and will log a message 

abOUt this (if xinetd logsto syslog, the 

message will besent at the log_alert priority 
level). If ahard limitisnot specified, it 
defaults to the soft limit increased by 1 
percent but the extra size must be within the 
parameters log_extra_min and log_extra_max 
(defined in config.h). 
Determi nes what information is logged when a server isstarted 
and when that server exits (the service ID is always included in 
the log entry). Any combination of thefollowing values may 
be specified: 

pid Logsthe server processID. (If the service is 

implemented by xinetd without forking another 
process, the logged processID will bea.) 
Logs the remote host address 
Logsthetimewhen theserver wasstarted. 
Logs the user ID of the remote user usi ng the 
RFC 931 i denti fi cation protocol. This option is 
available only for multithreaded stream servi ces. 
Logs thefact that a server exited alongwith the 
exitstatusorthetermination signal (the process 
ID isalso logged if the pid option isused). 
duration Logstheduration of a servi ce sessi on. 
Determi nes what information is logged when a server cannot 
be started (either because of a lack of resources or because of 
access control restri ctions). The servi ce ID is always included 
in the log entry alongwith thereason forfailure. Any 
combination of thefollowing values may be specified: 

host Logsthe remote host address 



HOST 
TIME 
USERID 



EXIT 
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rpcj/ersion 



passenv 
port 



time Logsthetimewhen the server wasstarted. 

userid Logstheuser ID of the remote user usi ng the RFC 
931 i denti fi cation protocol. Thisoption isavailable 
onlyformultithreaded stream servi ces. 

attempt Logsthefactthat afailed atterri ptwasm ade 

record Recordsinformation from the remote end in case 
theserver could not bestarted. Thisallows 
monitoring of attemptsto use the servi ce. For 
example, thelogin service logs the locai user, 
remote user, and terminal type. Currently, the 
services thatsupport thisoption areiogiun, sheii, 

exec, finger. 

DeterminestheRPC version foran RPC service. The versi on 
can beasinglenumberorarangein theform number- 
number. 

Thevalueof thisattribute isa list of stringsof theform 
name=vaiue. Thesestringswill beadded to theenvironment 
before starti ng a server (therefore the server's envi ronment wi 1 1 
include xinetd s envi ronment plus the specified strings). 
T h e vai u e of th i s attri bute i s a I i st of en vi ro n men t vari abl es 
from xinetd's envi ronment thatwi II bepassed to theserver. 
D eterni i n es th e servi ce port. I f th i s attri bute i s speci fi ed for a 
service listed in /etc/services, it must beequal to the port 
number listed in thatfile. 



You don't need to specify ali of the precedi ng attri butes for each service. The necessary attri butes for a service are the 



following: 




socket type 




user 


(non-unlisted servicesonly) 


server 


(non-i nternal servicesonly) 


wait 




protocol 


(RPC and unlisted servicesonly) 


rpc_version 


(RPC servicesonly) 


port 


(unlisted servicesonly) 



Thefollowing attri butes supportali assignment operators, except asindicated: 

only_f rom 

no_access 

log_on_success 

log_on_failure 

passenv 

env (does not support the -= operator) 

These attri butes can also appear morethan once in a service entry. The remaining attri butes support only the= operator and 
can appear at mostoncein a servi ce entry. 

The configurati on file may also contai n a single defaults entry that has theform: 

defaults 
{ 

<attribute> = <value><value> ... 



} 
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T his entry provides default attri bute values for servi ce entri es that don't speci fy those attri butes. Possi ble default attri butes: 
log_type 



log_on_success 

log_on_f ailure 

only_f rom 

no_access 

passenv 

instances 

disabled 



(cumulative effect) 
(cumulative effect) 
(cumulative effect) 
(cumulative effect) 
(cumulative effect) 

(cumulative effect) 



SIGUSR1 



SIGUSR2 



Attri butes with a cumulati ve effect can bespecified multi pie ti meswith the values specified each ti me accumulati ng (in other 
words, = does the samethingas+=). With theexception of disabled they ali havethesamemeaningasif they were specified 
in a servi ce entry, disabled determinesservicesthat are disabled even if they have entri es in the confi guration file T his allows 
for quick reconfigurati on byspecifying disabled serviceswith thedisabied attri bute instead of commenting them out. The 
value of this attri bute isa list of space-separated servicelDs. 

INTERNAI. SERVICES 

xinetd provides thefollowing services internally (both stream- and datagram-based): echo, time, daytime, chargen, and 
discard. These services are under the same access restrictionsas ali other services except for the ones that don't requi re xinetd 
to fork another process for them. Those ones (time, daytime, and the datagram-based echo, chargen, and discard) have no 
limitation in thenumber of instances. 

CONTROLLINO xinetd 

xinetd performs certain actionswhen it receivescertain signals. Theactionsassociated with the specific signalscan be 
redefined by editing contig.h and recompiling. 

Causesasoft reconfi guration, which meansthat xinetd rereads 
theconfiguration fi le and adjusts accordi ngly. 
Causesahard reconfiguration, which is the same as a soft 
reconfi guration except that serversfor services that areno 
longer availableareterminated. Access control isperformed 
again on running servers by checking the remote location, 
access ti mes and server instances. If thenumber of server 
instances islowered, some arbitrari ly picked servers will be 
killed to satisfy thelimit; this will happen after any servers are 
terminated becauseof failing the remote location or access 
timechecks. Also, if the intercept flagwasclear and is set, any 
ru n n i n g servers f o r th at servi ce wi 1 1 be term i nated; th e pu rpose 
of this is to ensurethat after a hard reconfiguration there will 
beno running servers that can accept packetsfrom addresses 
that do not meet the access control criteri a. 
C auses program termination. 
T er m i n ates al I ru n n i n g servers beforeterminatingxinetd. 
C auses an internai state dump (the default dump file is /tmp/ 
xinetd. dump; to change the filename, edit contig.h and 
recompile). 

Causesan internai consistency check toverify that the data 
structuresused bytheprogram havenot been corrupted. 
When the check iscompleted xinetd will generate a message 
that says if the check was successful or not. 



SIGQUIT 
SIGTERM 
SIGHUP 



SIGIOT 
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On reconfi guration, the log files are closed and reopened. Thisallows removal of old logfiles. Al so, thefollowing attri butes 
cannot bechanged on reconfiguration: socket_type, waìt, protocol, type. 

Xinetd LOG FORMAT 

Log entries are lines with thefollowing format: 

entry: servi ce- i d data 

T he data depends on the entry. Possi ble entry types: 

start G enerated when a server is started 

exit G enerated when a server exits 

fail Generated when itisnotpossibleto start a server 

data Generated when an atterri pt to start a server fails and the 

servi ce su pports the record logoption. 

userid Generated if the userid logoption isused. 

In thefollowing formats, theinformation enclosed in brackets appears if the appropriate logoption isused. 
A start entry has the format 

START: servi ce- i d [pid=%d] [from=%d.%d.%d.%d] [ time=t i me ] 
Time ÌS given aSyear/month/day(<ihour:minutes:seconds. 

An exit entry has the format 

EXIT: servi ce- id [type=%d] [pid=%d] [duration=%d(sec ) ] 

typecan beeither statusor signal. Thenumber is either the exit status or the signal that caused processtermination. 
A FAIL entry has the format: 

FAIL: servi c e - i d reason [from=%d.%d.%d.%d] [time=time] 

Possiblereasonsare 

f ork 



time 

address 

service_limit 

process_limit 

A data entry has the format 

DATA: servi ce-i d data 

Thedata logged depends on the servi ce. 
login 



A certain number of consecutive fork atterri pts fai I ed (this 
number is a confi gurable parameter). 
T hetimecheck failed. 
Theaddress check failed. 

T he allowed number of server instances for this service would 
beexceeded. 

A limiton thenumber offorked processeswasspecified and it 
would beexceeded. 



remote_user=%s local_user=%s tty=%s 

remote_user=%s veri fy=statuscommand=%sPossible status 
values: 

ok T he password wascorrect 
failed T he password wasincorrect 
baduser N o such user 

shell remote_user=%s local_user=%s command=%s 

finger received string Or EMPTY-LINE 
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A userid entry has the format 

USERID: text 

Thetext istheresponseof the RFC 931 daemon at the remote end excludingtheport numbers(which areincluded in the 
response). H ere'san example 

# 

# Sample conf iguration file for xinetd 
# 

defaults 
{ 

log_type = FILE /var/log/servicelog 
log_on_success = PID 
log_on_failure = HOST TIME RECORD 

only_from = 128.138.193.0 128.138.204.0 128.138.209.0 
only_from = 128.138.252.1 
instances = 10 
disabled = rstatd 

} 
# 

# Note 1 : the protocol attribute is not required 

# Note 2: the instances attribute overrides the default 
# 

service login 
{ 

socket_type = stream 
protocol = tcp 
wait = no 
user = root 

server = /usr/etc/in.rlogind 
instances = UNLIMITED 

} 
# 

# Note 1 : the instances attribute overrides the default 

# Note 2: the log on success flags are augmented 
# 

service shell 
{ 

socket_type = stream 

wait = no 

user = root 

instances = UNLIMITED 

server = /usr/etc/ in . rshd 

log_on_SUCCess += HOST TIME RECORD 

} 

service ftp 
{ 

socket_type = stream 
wait = no 
user = root 

server = /usr/etc/in.ftpd 
server_args = -1 
instances = 4 

log_on_success += DURATION HOST USERID 
access_times = 2:00-9:00 12:00-24:00 

} 
# 

# This entry and the next one specify internai services. Since this 

# is the same service using a different socket type, the id attribute 

# is used to uniquely identify each entry 
# 



service echo 
{ 

id = echo-stream 
type = INTERNAL 
socket_type = stream 
user = root 
wait = no 

} 

service echo 
{ 

id = echo-dgram 
type = INTERNAL 
socket_type = dgram 
user = root 
wait = no 

} 
# 

# Sample RPC service 
# 

service rstatd 

type = RPC 
socket_type = dgram 
protocol = udp 

server = /usr/etc/rpc . rstatd 
wait = yes 
user = root 
rpc_version = 2-4 

env = LD_LIBRARY_PATH=/etc/securelib 

} 
# 

# Sample unlisted service 
# 

service unlisted 
{ 

type = UNLISTED 
socket_type = stream 
protocol = tcp 
wait = no 

server = /home/user/some server 
port = 20020 

} 

Default configurati on file 
Default dump file 

SEEALSO 

inetd(8) 

PosteIJ., Edio Protocol, RFC 862, May 1983. 

Poste! J., Discard Protocol, RFC 863, M ay 1983. 

PosteIJ., Character Generator Protocol , RFC 864, M ay 1983. 

PosteIJ., Daytime Protocol, RFC 867, May 1983. 

PosteIJ., Harrenstien K., TimeProtocol, RFC 868, May 1983. 

StJohnsM ., Authentication Server, RFC 931, January 1985. 



FILES 

/etc/xinetd.conf 
/tmp/xinetd.dump 
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AUTHOR 

PanosTsirigotis (C S Department, U niversity of Colorado, Boulder) 
NOTES 

When theattributesoniy_from and no_access arenot specified fora servi ce (either di rectly or via defaults), the address check 
isconsidered successful (thatis, access will not bedenied). 

If theusERiD log option is specified and the remote RFC 931 server sends back an error reply, access will not bedenied. 

If theusERiD log option is specified and the remote host does not run an RFC 931 server, therewill beno indication in the 
log of that fact (other than the missing userid log entry). 

BUGS 

Supplementary group I D s are not supported. 

If the intercept flag isnot used, access control on the address of the remote host isnot performed when wait isyes and 

socket_type ÌS stream. 

If the intercept flag isnot used, access control on the address of the remote host forserviceswhere wait isyes and 
socket_type isdgram is performed only on the first packet. The server may then accept packetsfrom hostsnot in the access 
control list. Thiscan happen with RPC servi ces. 

UnlistedRPC services are not supported; thatis, ali RPC servicesmust beregistered in /etc/rpc. Specifyingan RPC service 
byitsRPC program number isnot (yet) possible. 

Thereisnowayto putasPACE in an environment variable. 

When wait isyes and socket_type is stream, thesocket passed to the server can only accept connections. 
The intercept flag is not supported for internai services or multi threaded services. 

Interception worksby forking a processthat acts as a fi Iter between the remote host(s) and the locai server. Thisobviously 
hasa performanceimpactwhich dependson thevolumeof information exchanged. It isup to you to make the compromise 
between security and performance for each service. 

PRONUNCIATICI 

xinetd ispronounced "zy-net-d." 

10 May 1992 

xinit 

xinit— X Window System initializer 
SYNOPSIS 

xinit [[client ] opti o n s ][— [ server [[display ] options ] 

DESCRIPTION 

The xinit program isused to start the X Window System server and a first client program on systems that can not start X 
directlyfrom /etc/init orin environments that use multiple window systems. When this first client exits, xinit will kill the 
X server and then terminate. 

If no specific client program isgiven on thecommand line, xinit will look for a file in the user's home directory called 
.xinitrc to run as a shell scriptto start up client programs. If no such fileexists, xinit will use the followingas a default: 

xterm -geometry +1+1 -n login -display :0 



xinit 




If no specifi c server program isgiven on thecommand line, xinit will look for a file in the user's home directory called 
.xserverrc to run asashell script to start up the server. If no such fileexists, xinit will usethefollowingas a default: 

X :0 

Notethat thisassumesthatthereis a program named X in thecurrentsearch path. H owever, serversareusually named 
xdispiaytype where dispiaytype is the type of graphics display that is dri ven by this server. T he site admi nistrator should, 
therefore, makea link to the appropriate type of server on the machine or create a shell script that runs xinit with the 
appropriate server. 

N ote, when usi ng a .xserverrc script besureto mark thereal X server asexec. Failing to do thiscan maketheX server slow 
to start and exit. For example 

exec Xdisplaytype 

An important poi nt is that programswhich are run by xinitrc should berun in the background if they do not exit right 
away, so that they don't prevent other programsfrom starti ng up. H owever, the last long-lived program started (usually a 
window manager or terminal emulatori should beleft in theforeground so that the seri ptwon't exit (which indicatesthat 
the user isdoneand that xinit should exit). 

An alternate client and/or server may bespecified on thecommand line. Thedesired client program and itsarguments 
should begiven as the first command-lineargumentsto xinit. To speci fy a parti cular server command line, append two 
dashes(— ) to the xinit command line (after any client and arguments) followed by thedesired server command. 

Both the client program nameand the server program namemust begin with aslash (/) or a peri od (.). Otherwise, they are 
treated as arguments to beappended to their respectivestartup lines. Thismakes it possibleto add arguments (for example, 
foreground and background colors) without havingto retype the whole command line. 

If an expl i ci t server nameisnot given and the first argument following the doublé dash (— ) is a colon followed by a digit, 
xinit will use that number as the di splay number instead of zero. AH remai ni ng arguments are appended to the server 
command line. 

EXAMPLES 

Following areseveral examplesof how command-li ne arguments in xinit areused: 

This will start up a server named X and run the user's xinitrc, if it exists, or else start an xterm: 

xinit 

Thisishowonecould start a specifi c type of server on an alternate display: 

xinit — /usr/X11R6/bin/Xqdss :1 

This will start up a server named X, and will append the given arguments to the default xterm command (it will ignore 

xinitrc): 

xinit -geometry =80x65+10+10 -fn 8x13 -j -fg white -bg navy 

Thiswill usethe command xsun -1 -c to start the server and will append the arguments -e widgetsto the default xterm 
command: 

xinit -e widgets — ./Xsun -1 -c 

Thiswill start a server named X on display 1 with the arguments -a 2 -ts: 

xinit /usr/ucb/rsh fasthost epupig -display ws:1 -- :1 -a 2 -t 5 

It will then start a rem ote shell on the machine fasthost in which it will run thecommand epupig, telling it to display back on 
the locai workstation. 

Following is a sample xinitrc that starts a clock, starts several termi nals, and leaves the window manager runningasthe 
"last" application. Assumingthatthewindow manager has been confi gured properly, theuserthen chooses the Exit menu 
item to shut down X. 

xrdb -load $HOME/ .Xresources 
xsetroot -solid gray & 
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xclock -g 50x50-0+0 -bw 0 & 
xload -g 50x50-50+0 -bw 0 & 
xterm -g 80x24+0+0 & 
xterm -g 80x24+0-0 & 
twm 

Sitesthat want to create a common startup environment could simply create a default xinit re that referencesa site-wide 
startup file: 

#!/bin/sh 

. /usr/local/lib/site.xinitrc 

Another approach isto write a script that starts xinit with aspecific shell script. Such scripts are usuai ly named xn, xstart, 
or startx, and areaconvenient way to provide a si mple interface for noviceusers: 

#!/bin/sh 

xinit /usr/local/lib/site.xinitrc -- /usr/X1 1R6/bin/X bc 



ENVIRO NMENT VARIABLES 

DISPLAY 
XINITRC 



T h i s vari abl e gets set to the nameof the di splay to which 
clients should connect. 

T his variable specifies an init file containing shell commands 
to start up theinitial Windows. By default, xinit re in the 
homedirectory will beused. 



FILES 

. xinitre 

xterm 

. xserverrc 

X 



Default client script 

C lient to run if .xinitre does not exist 

Default server script 

Server to run if .xserverrc does not exist 



SEEALSO 

x(l), startx(l), Xserver(l), xterm(l) 

AUTHOR 

Bob Scheifler (M IT Laboratory for Computer Science) 
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xkiii— Kill a client by itsX resource 
SYNOPSIS 

xkill [-display di spi ayname ] [-id resource] [-button number] [-trame] [-ali] 

D ESC RIPTIO N 

xkiii isa utility for forcing theX server to closeconnectionsto clients. T his program isvery dangerous, but isuseful for 
aborti ng programsthat havedisplayed undesired Windows on a user's screen. If no resource identifier isgiven with -id, xkiii 
will display a special cursor asa promptfor the user to select a window to be ki lied. If a pointer button ispressed over a 
nonroot window, the server will dose its connection to the client that created the window. 



xlogo 



OPTIONS 

-display di spi a y n a me T his option specifies the name of the X server to contact. 

-id resource T his option specifies the X identifier for the resource whose 

creator isto beaborted. If no resource isspecified, xkiii will 
display a special cursor with which you should sei ect avvi ndow 
tobekill. 

-button niimber Thisoption speci fi es the num ber of pointer button that should 

beused in selecting avvi ndow to kill. If the word "any" is 
specified, any button on the pointer may beused. By default, 
the first button in the pointer map (which isusually the 
leftmost button) isused. 

-ali Thisoption indicates that ali clients with top-level Windows on 

thescreen should be ki lied, xkiii will ask you to select the root 
window with each of thecurrently defined buttonsto giveyou 
several chancesto abort. U se of thisoption ishighly discour- 
aged. 

-trame Thisoption indicates that xkiii should ignore the standard 

conventi ons for fi nding top-level client Windows (which are 
typically nested insideawindow manager window), and 
simply bel ieve that you want to kill direct chi Idren of the root. 



XDEFAULTS 

Button Specifies a specific pointer button number ortheword "any" 

to usewhen selecting Windows. 

SEEALSO 

x(l), xwininto(l), xkiiiciient and xGetPointerMapping in theXIib ProgrammcrsM anual, Kiiiciient in theX Protocol 
Spedfication 

AUTHOR 

Jim Fulton (M IT X Consortium) and DanaChee(Bellcore) 
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xiogo— X Window System logo 
SYNOPSIS 

xlogo [ -t ool ki t opt i on . . . ] 

DESCRIPTION 

Thexiogo program displaystheX W indow System logo. 

OPTIONS 

xiogo acceptsall of the standard X Toolkit command-lineoptions, aswell asthefollowing: 

-snape Thisoption indicates that the logo window should beshaped 

ratherthan rectangular. 
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RESOURCES 

The default width and the default height areeach 100 pixels. This program uses the Logo widget in theAthena widget set. It 
understands ali of the Simple widget resource names and classes as well as: 

foreground (class Foreground) Specifies the color for the logo. T he default depends on 

whether reverseVideo isspecified. If reverseVideo isspecified, 

the default isxtDefauitForeground, otherwise the default is 

XtDefaultBackground. 

shapewindow (class shapewindow) Specifies that the window is shaped to the X logo. The default 

ÌS False. 



WIDGETS 

In order to specify resources, it isuseful to know the hierarchy of the widgets that compose xiogo. In thefollowing notation, 
indentation indicateshierarchical structure. The widget class nameisgiven first, followed by the widget instancename. 

XLogo xlogo 

Logo xlogo 

ENVIRONMENT 

display To get the default host and display number. 

xenvironment To get the name of a resource fi le that ovari des the global 

resources sto red in the resource jianager property. 

FILES 

<xRoot>/iib/xn/app-defauits/xLogo Specifies required resources 
SEEALSO 

x(l), xrdb(l) 

AUTHORS 

Olliejonesof Apollo Computer andjim Fulton of theM IT X Consortium wrote the logo graphics routine, based on a 
graphic design by Danny Chongand RossChapman of Apollo Computer. 
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xisatoms— List interri ed atomsdefined on server 
SYNOPSIS 

xlsatoms [ -options . . . ] 

D ESC RIPTIO N 

xlsatoms liststhe interned atoms. By default, ali atoms starti ngfrom 1 (thelowest atom value defined by the protocol) are 
listed until unknown atom isfound. If an explicit rangeisgiven, xlsatoms will try ali atoms in therange, regardlessof 
whether or not any are undefi ned. 



OPTIONS 

-display dpy 
-format stri n g 



-range [I ow] - [hi gh ] 
-name stri n g 

SEEALSO 

x(l), Xserver(l), xprop(l) 

ENVIRONMENT 

DISPLAY 

AUTHOR 

Jim Fulton (M IT X Consortium) 



xlsclients 



Thisoption specifies the X server to which to connect. 
Thisoption specifies a printf-stylestring used to list each 
atom <vaiue,name> pai r, printed in that order (vaiue isan 
unsigned long and name isa ctiar *). xisatoms will supply a 
newlineat the end of each line The default is%id\t%s. 
Thisoption specifies the range of atom valuesto check. If i ow 
isnotgiven, avalueof 1 isassumed. If hi gh isnotgiven, 
xisatoms will stop at the first undefined atom at or abovei ow. 
Thisoption specifiesthenameof an atom to list. If the atom 
doesnot exist, a messagewill be printed on the standard errar. 



To get the default host and display to use 
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xlsclients 

xisciients— List client applications running on a display 
SYNOPSIS 

xlsclients [ -display di s pi a y n a me ] [-a] [-1] [ -m maxcmdlen ] 

DESCRIPTION 

xlsclients is a utility for listing information about the client applications running on a display. It may beused to generate 
scripts representing a snapshot of the user's current session. 

OPTIONS 

-display di spi a y n a me 
-a 

-1 

-m maxcmdlen 

ENVIRONMENT 

DISPLAY 



Thisoption specifies the X server to contact. 
Thisoption indicete that clientson ali screensshould be 
listai. By default, onlythose clientson the default screen are 
listed. 

Listin longformat, givingthewindow name, icon name, and 
class hi nts in addi ti on to the machine name and command 
stri ng shown i n the default format. 
Thisoption specifies the maximum numberof charactersin a 
command to print out. The default is 10000. 



To get the default host, display number, and screen. 
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SEEALSO 

x(l), xwininfo(l), xprop(l) 

AUTHOR 

J im Fulton (M IT X C onsortium) 
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xlsfonts 

xisfonts— Server font list displayer for X 
SYNOPSIS 

xlsfonts [-options ...] [-fn pattern] 

D ESC RIFTIO N 

xisfonts lists thefonts that match thegiven pattern. The wildcard character * may beused to match any sequence of 
characters (including none), and ? to match any single character. If no pattern isgiven, * isassumed. 

The* and ? characters must bequoted to prevent them from beingexpanded by theshell. 
OPTIONS 

-display host : dpy 
-1 

-11 
-111 
-m 

-C 

-1 

-w wi dt h 
-n col umns 



-o 



-f n pattern 

SEEALSO 

x(l), xserver(l), xset(l), xfd(l), X Logicai Font D escription Conventions 



Thisoption specifiestheX server to contact. 
Lists someattributes of thefonton onelinein addition to its 
name 

Lists font propertiesin addition to -I output. 
Lists character metri cs in addition to -n output. 
Thisoption indicatesthat long listi ngsshould also printthe 
minimum and maximum boundsof each font. 
Thisoption indicatesthat li sti ngs should use multiple 
columns. Thisisthesameas-n e. 
Thisoption indicatesthat listi ngs should use a single column. 
Thisisthesameas-n 1. 

Thisoption specifies the width in characters that should be 
used in figuri ng out how many columns to print. The default 
is 79. 

Thisoption speci fi es the number of columns to use in 
displaying the output. By default, itwill attemptto fitasmany 
columns of font names into the number of character specified 

by -w wi dt h . 

T his option indicates that the output should be left unsorted. 
Thisoption indicatesthat xisfonts should do an openFont 
(and QueryFont, if appropriate) ratherthan ai_istFonts.Thisis 
useful if ListFonts or ListFontswitninfo fai I to list a known 
font(asisthecasewith somescaled fontsystems). 
Thisoption specifies the font name pattern to match. 



xmag 

ENVIRONMENT 

display To get the default host and display to use 

BUGS 

Doingxisfonts -ì can tieup your server for a very long time. Thisisreally a bug with single-threaded nonpreemptable 
servers, notwith this program. 

AUTHOR 

M ark Li Ili bridge (M IT Project Athena), Jim Fulton (M IT X Consortium), and Phil Karlton (SGI) 
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xmag 

xmag— M agnify partsof thescreen 
SYNOPSIS 

xmag [ -mag magfactor ][-source g eo m ][— tool ki topti on ...] 

D ESC RIPTIO N 

The xmag program allowsyou to magnify porti onsof an X screen. If no explicit region isspecified, asquarewith the pointer 
in the upper-left corner isdisplayed i ndicating the area to beenlarged. The area can bedragged out to the desi red sizeby 
pressing Button 2. After a region hasbeen selected, awindow ispopped up showinga blown-up version of the region in 
which each pixel in thesourceimageisrepresented by asmall squareof the same color. Pressing Button 1 in theenlargement 
window showstheposition and RGB valueof the pixel under the pointer until the button isreleased. Typingq or "C in the 
enlargement wi ndow exits the program. The application has fi ve buttons across its top. C lose deletes this parti cui ar 
magnification instance. Replace bri ngsup therubber band selector again to select another region for this magnification 
instance. N ew bri ngsup therubber band selector to create a new magnification instance. Cut puts the magnification image 
into the primary selection. Paste copi es the primary selection buffer into xmag. N otethatyou can cut and paste between xmag 
and thebitmap program. Resizing xmag resi zes the magnification area, xmag preservesthecolormap, visual, and window depth 
of thesource. 

WIDGETS 

xmag usestheX Toolkit and the Athena W idget Set. Themagnified image isdisplayed in the Scale widget. For more 
information, see the Athena Widget Set documentation. Following is the widget structureof the xmag application. Indenta- 
tion indicates hierarchical structure. The widget class nameisgiven first, followed by the widget instance name. 

Xmag xmag 

RootWindow root 
TopLevelShell xmag 
Paned panel 

Paned pane2 

Command dose 
Command replace 
Command new 
Command select 
Command paste 
Label xmag label 
Paned pane2 

Scale scale 
OverrideSbell pixShell 
Label pixLabel 
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OPTIONS 

-source geom This option specifies the size and/or location of the source 

region on the screen. By default, a 64x64 square is provided 
for the user to select an area of the screen. 

-mag integer T his option indicete the magnifi cation to be used. T he 

default is 5. 

AUTHORS 

D ave Sterni icht and DavorM atic (M IT X Consorti um) 
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xmkmf 

xmkmf— C reate a Makef ile from an Imakef ile 

SYNOPSIS 

xmkmf [-a][topdir [ curdir ]] 

DESCRIPTION 

The xmkmf command isthenormal way to create a Makef ile from an imakef ile shipped with third-party software. 

When invoked with no argumentsin a directory contai ni ngan imakeme, theimake program isrun with arguments 
appropri ate for your system (configured into xmkmf when X was built) and generate a Makef ile. 

When invoked with the -a option, xmkmf bui Ids the Makef ile in the current directory, and then automatica! ly executemake 
Makefiies (in casethere are subdirectories), make inciudes, and make depend foryou. This isthe normal way to configure 
software that isoutside the X Consortium buildtree. 

If working inside the X Consortium build tree (unlikely unlessyou arean X developer, and even then this option isnever 
really used), thetopdir argument should be specified astherelativepathnamefrom the current directory to the top of the 
build tree Optionally, curdir may be specified as a relative pathnamefrom the top of the build treeto the current directory. 
It isnecessary to supply curdir if the current directory has subdirectories, or the Makef ile will not beableto build the 
subdirectories. If atopdir isgiven, xmkmf assumes nothing is installed on your system and looksfor files in the build tree 
instead of using the installed versions. 

SEEALSO 

imake(l) 
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xmodmap 

xmodmap— Utility for modifying keymapsin X 
SYNOPSIS 

xmodmap [-options ...] [filename] 

DESCRIPTION 

The xmodmap program isused to edit and display the keyboard modifier map and keymap tablethat are used by client 
applicationsto convert event keycodesinto keysyms. It is usuai ly run from the user's sessi on startup script to configure the 
keyboard accordi ngto personal tastes. 
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OPTIONS 

T he followi ng options may beused with xmodmap: 

-display display This option specifies the host and display to use. 

-heip Thisoption indicete that a brief descri ption of thecommand- 

lineargumentsshould beprinted on thestandard errar 
channel. Thiswill bedonewhenever an unhandled argument 

isgiven tO xmodmap. 

-grammar Thisoption indicates that a help messagedescribingthe 

expression grammar used in filesand with -e expressions 
should beprinted on thestandard errar. 

-verbose Thisoption indicates that xmodmap should print logging 

information as it parses its input. 

-quiet T his option turns off the verbose logging. T his is the default. 

-n Thisoption indicates that xmodmap should notchangethe 

mappings, but should display whatitwould do, likemake(l) 
doeswhen given thisoption. 

-e expression T his option specifies an expression to be executed. Any 

number of expressions may be specified from thecommand 
line. 

-pm Thisoption indicates that the current modifier map should be 

printed on thestandard output, 
-pk Thisoption indicates that the current keymap table should be 

printed on thestandard output, 
-pke Thisoption indicates that the current keymap table should be 

printed on thestandard output in theform of expressionsthat 

can befed back to xmodmap. 

-pp Thisoption indicates that thecurrent pointer map should be 

printed on thestandard output. 

A lonedash means that the standard input should beused as 
the input file. 

The fi lename speci fi es a fi le contai ning xmodmap expressions to be executed. This fi lei susually kept in the user's home 
directory with a name like .xmodmaprc. 

EXPRESSION GRAMMAR 

The xmodmap program readsa list of expressions and parses them ali befo re atterri ptingto executeany of them. Thismakes it 
possi bleto referto keysymsthat are bei ng redefined in a naturai way without havingto worry asmuch about name confi icts. 



keycode NUMBER = KEYSYMNAME 



keycode any = KEYSYMNAME 



keysym KEYSYMNAME = KEYSYMNAME 



The list of keysyms is assigned to the indicated keycode (which 
may be specified in decimai, hex, oroctal and can be 
determined by runningthexev program. 
If no existing key has the specified list of keysyms assigned to 
it, a spare key on the keyboard isselected and the keysyms are 
assigned to it. The list of keysyms may be specified in decimai, 
hex, or octal. 

TheKEYSYMNAME on the left side is tran slated into matching 
keycodesused to perform thecorrespondingset of keycode 
expressions. The list of keysym namesmay befound in the 
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clear MODI FI ERNAME 



add MODI FI ERNAME = KEYSYMNAME 



remove MODI FI ERNAME = KEYSYMNAME 



pointer =default 
pointer = NUMBER 



header fi le <X1 1 /keysymdef . h (WÌthOUt the XK_pref ix) or the 

keysym database <xRoot>/iib/xn/xKeysymDB, where<xRoot> 
refersto theroot of the X 11 instali tree. N otethat if thesame 
keysym isboundto multiple keys, the expressi on isexecuted 
for each matching keycode. 

This removes ali entri es in the modifier map for the given 
modifier, wherevalid names are snitt, Look, control, Modi, 
Mod2, Mod3, Mod4, andniod5 (case does not matter i n modifier 
names, although it does matter for ali other names). For 
example, ciear Lock wi II remove any keys thatwereboundto 
theshift lock modifier. 

Thisaddsall keys contai ni ng the given keysymstothe 
indicateci modifier map. The keysym names are evaluated after 
ali input exp ressi ons are read to makeit easy to write 
expressionsto swap keys. (Seethe"Examples" subsection). 
Thisremovesall keys contai ni ng the given keysymsfrom the 
indicateci modifier map. U nlike add, the keysym names are 
evaluated asthe line is read in. Thisallowsyou to remove keys 
from a modifier without having to worry about whether or not 
they have been reassi gn ed. 

This sets the pointer map back to its default setti ngs(button 1 
generates a code of 1, button 2 generates a 2, and so on). 
Thissetsto pointer map to contai n the indi cated button 
codes. T he I ist always starts wi th the first physical button. 



Linesthat begin with an exclamation point (i) aretaken ascomments. 

If you want to changethebinding of a modifier key, you must also remove it from the appropriate modifier map. 
EXAMPLES 

M any pointers are desi gned such that the first button is pressed using the index finger of theright hand. Peoplewho areleft- 
handed frequently find that it ismorecomfortableto reverse the button codes that are generated so that the primary button 
is pressed using the index finger of theleft hand. This could bedoneon a 3 button pointer asfollows: % xmodmap -e "pointer 

=3 2 1". 

M any applicationssupport the noti on of M età keys (similar to Control keys except that M età isheld down instead of 
Control). H owever, someserversdo not have a M età keysym in the default keymap table, so oneneedsto beadded by hand. 
Thefollowing command will attach M etato theM ultilanguage key (sometimes labeled Compose Character). It also takes 
advantageof thefact that appi ications that need a M età key simply need to get the keycode and don't requi re the keysym to 
bein the first column of the keymap table. This means that applications that arelookingfor a M ulti key (includi ng the 
default modifier map) won't noticeany change. Example: 
% xmodmap -e "keysym Multi_key = Multi_key Meta_L" 

Similarly, some keyboards have an Alt key but no M età key. In that case thefollowing may beuseful: 

% xmodmap -e "keysym Alt L = Meta L Alt L" 

Oneof the more si m pi e, yet convenient, uses of xmodmap isto set thekeyboard's"rubout" key to generate an alternate 
keysym. This frequently involvesexchanging Backspacewith Delete to bemorecomfortableto the user. If thettyModes 
resourcein xte™ issetaswell, ali terminal emulator Windows will use thesame key for erasi ng characters: 



% xmodmap -e "keysym BackSpace = Delete" 

% echo "XTerm*ttyModes : erase "?" | xrdb -merge 
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Somekeyboardsdo not automati cally generate lessthan and greaterthan characterswhen the comma and period keysare 
shifted. Thiscan be remedied with xmodmap by resetting the bindingsfor the comma and period with the following seri pts: 

! make shift-, be $<$ and shift-. be $>$ 

keysym comma = comma less 
keysym period = period greater 

0 ne of the more irritati ngdifferences between keyboardsis the location of the Control and Shift Lock keys. A common use 

of xmodmap isto swap thesetwo keysasfollows: 

i 

! Swap Caps_Lock and Control_L 
! 

remove Lock = Caps_Lock 
remove Control = Control_L 
keysym Control_L = Caps_Lock 
keysym Caps_Lock = Control_L 
add Lock = Caps_Lock 
add Control = Control_L 

Thekeycodecommand isuseful forassigning the same keysym to multiple keycodes. Although unportable, italso makesit 
possi bleto write seri pts thatean reset the key board to a known state. The following script setstheBackspacekey to generate 
D elete (asshown earlier), flushes al I existing caps lock bindings, makes the Caps Lock key beacontrol key, makeF5 generate 
Escape, and makes Break/Reset bea shift lock. 

! On the HP, the following keycodes have key caps as listed: 

! 101 Backspace 

! 55 Caps 

! 14 Ctrl 

! 15 Break/Reset 

! 86 Stop 

! 89F5 

keycode 101 = Delete 
keycode 55 = Control_R 
clear Lock 

add Control = Control_R 
keycode 89 = Escape 
keycode 15 = Caps_Lock 
add Lock = Caps_Lock 

ENVIRONMENT 

display To get default host and display number 

SEEALSO 

x(l), xev(l), xiib documentation on key and poi nter events 
BUGS 

Every time a keycode expression isevaluated, the server generatesawappingNotify event on every client. Thiscan cause some 
thrashing. Ali of thechangesshould bebatched together and doneat once. Clientsthat recei ve key board input and ignore 
MappingNotity eventswill not notice any changes made to keyboard mappings. 

xmodmap should generate add and remove expressionsautomatically whenever a keycode that isalready bound to a modifier is 
changed. 
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Thereshould bea way to have the remove expression accept keycodesaswell as keysymsfor thosetimeswhen you really mess 
up your mappings. 

AUTHOR 

Jim Fulton (M IT X Consortium), rewritten from an earlier versi on by David Rosenthal (Sun M icrosystems) 
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xon 

xon— Start an X program on a remote machine 
SYNOPSIS 

xon remote-host [-access] [-debug] [-name window-name] [-nols] [-screen screen-no] [-user user-name] [command ...] 

D ESC RIPTIO N 

xon runsthespecified command (default xterm -is) on the remote machine usi ng rsh, remsh, or rcmd. xon passes the display, 
xauthority, and xuserfilesearchpath envi ronment variables to the remote command. 

When no command isspecified, xon runs xterm -is.lt addi tionally specifies the application nameto bexterm-remote -h os t 
and thewindow titleto be -firemote-host. 

xon can only work when the remote hostwi II ali ow you to log in without a password, by havingan entry in the .rnosts file 
permitti ng access. 

OPTIONS 

N ote that the optionsfollow the remote hostname (asthey do with nogin). 

-access Runsxhost locally to add the remote host to the host access list 

in theX server. Thiswon'twork unlessxnost isgiven 
permission to modify theaccess list. 

-debug Normally, xon disconnects the remote process from stdin, 

stdout, and stderrto elimi natethedaemon processesthat 
usually connectthem across the network. Specifyi ng the -debug 
option leavesthem connected so that errar messagesfrom the 
remote execution aresent back to the ori gi nati ng host. 

-name window-name Thisspecifiesa different application nameandwindowtitle 

for the default command (xterm). 

-nois N ormally xon passesthe -is option to the remote xterm; this 

option suspends that behavior. 

-screen screen-no T his changes the screen number of theDisPLAY variable passed 

to the remote command. 

-user user-name By default, xon Simply USeS rsh/remsh/rcmd tO COnnect tO the 

remote machine using the same username as on the locai 
machine. Thisoption causesxon to specify an alternative 
username Thiswill notwork unlessyou haveauthorization to 
access the remote account, by piaci ngan appropriate entry in 
the remote user's . rnosts fi le. 

BUGS 

xon can get easily confused when the remote host, username, or various envi ronment variable values contai n whitespace. 
xon hasno way to send the appropri ateX authorization information to the remote host. 

X Veraon 11 Re!ease6 
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xpmtoppm 

xpmtoppm— Convert an Xll pixmap into a portablepixmap 
SYNOPSIS 

xpmtoppm [ x p mf i I e J 

DESCRIVO N 

ReadsanXll pixmap (XPM version lor3) asinput. Producesa portable pixmap as output. 
KNOWN BUGS 

Thesupport to XPM version 3 is limitaci. Commentscan only be single lines and theremust befor every pixel a default 
color namefor a color type visual. 

SEEALSO 

ppmtoxpm(l), ppm(5) 

XPM M anual byArnaud LeHors(iehors@mirsa.inrìa.fr) 

AUTHOR 

Copyright (c) 1991 byjef Poskanzer. 

Upgraded to support XPM version 3 by Arnaud Le H ors(ienors@mirsa. inria.tr) 9 Aprii 1991 

16 August 1990 
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xprop— Property displayer forX 
SYNOPSIS 

xprop [-help] [-grammar] [-id d] [-root] [-name name] [-trame] [-font font] 
[-display display] [-len n] [-notype] [-fs file] [-remove p r o per t y • na me ] 
[-spy] [-f atom format [dformat]]* [format [dformat] atom]* 



SUMMARY 

The xprop utility isfor displaying window and font propertiesin an X server. Onewindow or font isselected usi ng the 
command-lineargumentsor possi bly in the case of a window, by clicking on the desi red window. A list of properties isthen 
given, possibly with formatting information. 



0PTI0NS 



-help 
-grammar 
-id i d 



Print out a summary of command-lineoptions. 
Print out a detailed grammar for ali command-lineoptions. 
Thisargument allowstheuser to select window id on the 
command li ne rather than using the pointer to select thetarget 
window. Thisisvery useful indebuggingX applicationswhere 
thetarget window isnot mapped to thescreen or wherethe 
useof the pointer might be impossi ble or interfere with the 
application. 

Thisargument allowstheuserto specifythat the window 
named name is the target window on thecommand line rather 
than using the pointer to select thetarget window. 
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■font font 
-root 

-display di spi ay 
•len n 
-notype 
-fs file 
-trame 

-remove property-name 
-spy 

-f name f or ma t [dformat ] 



T his argument allows the user to specify that the properties of 
fontf ont should bedisplayed. 
T his argument specif ies that X 's root wi ndow is the target 
window. This isuseful in situati onswhere the root wi ndow is 
completely obscured. 

Thisargument allows you to specify the server to connect to; 
seex(l). 

Specifiesthat at most, n bytes of any property should be read 
ordisplayed. 

Specifi es that the typeof each property should not be 
di splay ed. 

Specifi es that filef i i e should beused asa sourceof more 
formatsfor properties. 

Specifiesthat when selecting a window by hand (that is, if 
neither -name, -root, nor -id isgiven), look atthewindow 
manager frame (if any) instead of lookingfortheclient 
window. 

Specifi es the name of a property to be removed from the 
indicateci window. 

Examine window properties forever, lookingfor property 
changeevents. 

Specifiesthat theformatforname should bef orma t and that 
the dformat for name should be df ormat . If dformat ismissing, 
■= $o+\n" isassumed. 



DESCRIPTION 

For each of these properties, itsvalueon theselected window or font isprinted usi ng the supplì ed formatti ng information, if 
any. If no formatting information issupplied, internai defaultsareused. If a property is not defined on theselected window 
or font, not detined isprinted as the value for that property. If no property list isgiven, ali the properties possessed by the 
selected window or font are printed. 

A window may be selected in oneof four ways. First, if the desi red window isthe root window, the - root argument may be 
used. If the desi red window is not the root window, it may be selected in two wayson thecommand line, either by id 
number, such asmight beobtained from xwininto, or by name if the window possessesa name. The -id argument selectsa 
window by id number in either decimai or hex (must start with 0x) whilethe -name argument selectsa window by name. 

Thelast way to select a window does not involve thecommand line at ali. If noneof -font, -id, -name, and -root are 
speci fi ed, a crosshairscursor isdisplayed and the user isallowed to chooseany visi ble window by pressing any pointer button 
in the desi red window. If it is desi red to display properties of a font asopposed to a window, the -font argument must be 
used. 

Other than the precedi ng four arguments and the -neip argument for obtaining help, and the -grammar argument for I isti ng 
the full grammar for thecommand line, ali the other command-li ne arguments are used in specifying both the format of the 
properties to bedisplayed and how to display them. The -ien n argument speci fi esthatat most, n bytes of any given 
property wi II beread and displayed. This isuseful, forexample, when displayingthecut buffer on the root window, which 
could run to several pagesif displayed in full. 

N ormally, each property name isdisplayed by pri nting first the property name then itstype (if it hasone) in parentheses, 
followed by its value. The -notype argument specifiesthat property types should not bedisplayed. The -fs argument isused 
to specify a file contai ni ng a list of formatsfor properties, whilethe -f argument isused to specify the format for one 
property. 



xprop 



The formatti ng information for a property actually consistsof two parts, a format and a dformat. The format speci fi es the 
actual formatti ng of the property (that is, isit macie up of words, Pytes, or longs?, and so on) whi le the dformat specifies how 
the property should Pedisplayed. 

Thefollowing paragraphsdescriPehow to constructformatsand dformats. H owever, for thevast majority of usersand uses, 
thisshould not Penecessary asthePuilt-in defaults contai n theformatsand dformats necessaryto display ali thestandard 
properties. It should only Pe necessaryto specify formatsand dformats if a new property isPeingdealt with or the user 
dislikes the standard display format. N ew users especi al ly are encouraged to skip thispart. 

A format consistsof a 0, 8, ie, or 32 followed Py asequenceof oneor more format characters. Thea, 8, 16, or 32 specifies 
how many Pits per field there are in the property. 

Zero is a special case that means use thefield size information associated with the property itself. (Thisisonly needed for 
special cases liketype integer, whi eh is actually three different types, dependi ng on the size of the fieldsof the property.) 

A valueof 8 means that the property isasequence of Pytes, whi le a valueof 16 means that the property isasequence of 
words. The differencePetween thesetwo liesin the fact that the sequenceof words wi II Pe Pyte swapped whilethesequence 
of Pytes will notPewhen read Py a machine of the opposite Pyte orderof the machine that originally wrote the property. For 
more information on how properties are formatted and stored, consult theXIib manual. 

After the size of the fieldshasPeen specified, it is necessaryto specify the typeof each field (isit an integer, a string, an atom, 
or what?) Thisisdoneusing one format character per field. If there aremorefieldsin the property than format characters 
supplied, thelast character will Perepeated as many timesas necessary for the extra fields. The format characters and their 
meaningareasfollows: 

a Thefield holdsan atom numPer. A field of thistype should Pe 

of size 32. 

b Thefield isa Boolean. A 0 means false whi le anything else 

meanstrue. 

c Thefield isan unsigned numPer, a cardinal. 

i Thefield isa signed integer. 

m Thefield isasetof Pitflags, 1 meaningon. 

s Thisfield and the nextones— unti I eitheraO or the end of the 

property— represent a sequence of Pytes. T hisformat character 
isonly usaPlewith a field sizeof 8 and ismost often used to 
represent a string. 

x Thefield isa hex numPer (li ke c but displayed in hex— most 

useful for displayingwindow idsand thelike). 

An example format is32ica, which is the format for a property of three fieldsof 32 Pits each— the first holding a signed 
integer, thesecond an unsigned integer, and thethird an atom. 

T he format of a dformat, unii ke that of a format, is not so ri gid. The only li mitationson a dformat is that one may not start 
with a letter or adash. T hi s isso that it can be distingui shed from a property nameor an argument. A dformat is a text string 
contai ning special characters instructing that various fields beprinted at variouspointsin a manner similar to the formatti ng 
stri ng used Pyprintf. For example the dformat is ( $0, $1 \)\n would render the point 3, -4, which has a format of32ii as 

is ( 3, -4 )\n. 

Any character otherthan a$, ?, \, or a ( in a dformat printsas itself. To print out a$, ?, \, or (, precede it with a\. For 
example, to print out a$, use \$. Several special Packslash sequences are provi ded asshorteuts. \n will cause a newlineto be 
displayed, while \t will causeataP to Pedisplayed. \o, whereo isan octal numPer, will display character numPer 0. 

A $ followed Py a number n causes field number n to be displayed. T he format of the displayed field dependson the 
formatti ng character used to descriPeit in the corresponding format. In other words, if a cardinal isdescribed by c, it will 
print in decimai, whileif it isdescriPed Py an x, it is displayed in hex. 
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If thefield isnot present in theproperty (this is possiblewith someproperties), <fieid not avaiiabie> i s di splayed instead. 
$n+ will display field number n, then a comma, then field number n+1, then another comma, then . . . until the last field 
defined. If field n isnot defi ned, nothing isdisplayed. Thisisuseful for a property that isa list of values. 

A ? isused to start a condì tional expression, akind of if-then statement. ?exp <t ext ) will display text if and only if ex p 
evaluatesto non-zero. Thisisuseful fortwo things. First, it allows fields to bedisplayed if and only if aflag is set. And 
second, it allows a valuesuch as a state number to bedisplayed asa namerather than asjust a number. The syntax of ex p isas 
follows: 

exp : : = t e r m ] t e r m=ex p j !exp 
t e r m : : = n j $n j mn 

The ! operator isa logicai not, changingo to 1 and any non-zero valueto a. = isan equali ty operator. N ote that internai ly, ali 
expressionsareevaluated as 32-bit numbers, so -i isnot equal to 65535. = returnsi if thetwo values are equal and 0 if not. n 
represents the Constant valuen while $ n represents the valueof field number n. mn isi if flag number n in the first fidd 
having format character m in the corresponding format is 1; 0 otherwise. 

Examples: ?m3(count: $3\n) displays field 3 with a label of count if and only if flag number 3 (count startsat 0!) ison. 
?$2=0(True)?!$2=0(Faise) displaysthe inverted valueof field 2 asa Boolean. 

In order to display a property, xprop needsboth a format and adformat. Beforexprop usesits default values of a format of 32x 
and a df ormat of ■ = { $0+ }\n", itsearchesseveral placesin an attempt to find morespecificformats. First, asearch ismade 
using the nameof theproperty. If this fai Is, asearch ismade usi ng the typeof theproperty. This allows typesTRiNG to be 
defined with one set of formats while allowing property wmjiame, which isof type string to be defi ned with a different 
format. In thisway, the display formats for agi ven typecan beoverridden for specific properties. 

The locati onssearched are in order: the format, if any, specified with theproperty name(asin 8x wm_name), the formats 
defined by -f options in last to first order, the contentsof the fi le specified by the -fs option if any, the contentsof the file 
specified by theenvironmental variablexpROPFORMATs if any, and fi nal ly xprop's bui It-in file of formats. 

T he format of the fi lesreferred to bythe -fs argumentand thexpROPFORMATs variableisoneor morelinesof thefollowing 
form: 

name f or ma t [df or mat ] 

Wherename iseither the nameof a property or the nameof a type, format is the formatto beused with name, and df or mat is 
thedformatto beused with name. If df or mat isnot present, "=$0+\n" isassumed. 

EXAMPLES 

To display the nameof the rootwindow: xprop -root wm_name 

To display thewindow manager hints for the clock: xprop -name xciock wm_hints 

To display the start of the cut buffer: xprop -root -ien 100 cut_buffer0 

To display the point azeofthefixed font: xprop -font fixed point_size 

To display ali the properties ofwindow #0x200007: xprop -id 0x200007 

ENVIR0NMENT 

display Toget default display. 

xpropformats Specifi es the name of a f i le f rom which additional formats are 

to beobtained. 

SEEALS0 

x(l), xwininfo(l) 
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AUTHOR 

M ark Li Ili bridge (M IT Project Athena) 
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xrdb— X server resource database utility 
SYNOPSIS 

xrdb [ -option . . . ] [fi I e n a me ] 

DESCRIVO N 

xrdb isused to get or set the contents of the resource_manager property on therootwindow of screen 0, or the 
screen_resources property on therootwindow of any or ali screens, or everything combined. You would normally run this 
program from yourX startup file. 

M ostX clients use the resource_manager and screen_resources propertiesto get user preferences about color, fonts, and so on 
for applicati ons. H aving this informati on in the server (whereit isavailableto ali clients) instead of on disk solvesthe 
problem in previous versionsof X that required you to maintain defaultsfileson every machinethat you might use. It also 
allowsfor dynamic changing of defaults without editing files. 

The resource_manager property isused for resources that applyto ali screens of the display. T he screen_resources property 
on each screen specifies additional (or overriding) resources to beused for that screen. (When there isonlyone screen, 
screen_resources is normally not used; ali resources are just placed in theREsouRCEjiANAGER property.) 

T he file specified by filmarne (or the contents from standard input if - or no filenameisgiven) isoptionally passed through 
theC preprocessor with thefollowingsymbolsdefined, based on thecapabilitiesof theserver bei ng used: 

Thehost name portion of the display to which you are 
connected. 

ThesERVERHosThostnamestring turned into a legai identifier. 

For example, my-dpy.lcs.mit.edu beCOmeSSRVR my dpy Ics 
mit edu. 

The same as serverhost. 
Thenumberof thedisplay on theserver host. 
The name of the host on which xrdb isrunning. 
ThecLiENTHosT hostname stri ng turned into alegal identifier. 
For example, "expo.ics.mit.edu" becomescLNT expo ics mit 

edu. 

Thevendor release num ber for the server. The interpretati on 
of this number will vary depending on vendor. 
Thex protocol minorversion supported by th i s server 
(currently 0). 

Thex protocol major version supported by this server (should 
always ben). 

A stri n g I i teral speci fyi n g the vendo r of th e server. 
T he vendor name stri ng turned into alegal identifier. For 
example, "mit x consortium- becomesvNDR_MiT_x Consortium. 
A symbol isdefined for each protocol extension supported by 
theserver. Each extension stri ng name is turned into a legai 
identifier. For example, m x3d-pex" becomesEXT_x3D_PEx. 



SERVERHOST=host name 



SRVR name 



HOST=h 0 s t name 
DISPLAY_NUM=num 
CLIENTHOST=host name 
CLNT name 



RELEASE=n u m 



REVISION=num 



VERSION=num 



VENDOR=" vendor 
VNDR name 



EXT name 



682 
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NUM_SCREENS=num 
SCREEN_NUM=nLim 
BITS PER RGB=num 



CLASSAI su al ci ass 



CLASS vi sual ci ass=vi sual i d 



COLOR 



CLASS_visualclass_deptr,=num 



HEIGHT=num 
WIDTH=num 
PLANES=num 
X_RESOLUTION=num 
Y RESOLUTION=num 



The total number of screens. 

Thenumber of thecurrentscreen (from zero). 

The number of significar^ bitsin an RGB color specificati on. 

This is the log base 2 of the number of disti net shades of each 

primary that the hardware can generate. N otethat it usually is 

not rdated to planes. 

Oneof StaticGray, GrayScale, StaticColor, PseudoColor, 
TrueColor, DirectColor. This isthevisual Class Of therOOt 

window. 

The visual class of theroot window in aform you can #ifdef 

on.Thevalueisthenumeric id of the visual. 

D efi ned only if class is one of staticcoior, Pseudocolor, 

TrueColor, Or DirectColor. 

A symbol isdefined for each visual supported for thescreen. 

Thesymbol i ncludes the class of the vi sual and itsdepth; the 

valueisthenumeric id of the visual. (If morethan one vi sual 

has the same class and depth, the numeri c id of the first one 

reported by the server is used.) 

Theheight of theroot window in pixel s. 

Thewidth of therootwindow in pixels. 

The number of bit planes (the depth) of theroot window. 

T he x resolution of thescreen in pixels per meter. 

T he y resolution of thescreen in pixels per meter. 



SRVR_name, cLNT_name, vNDRjiame, and EXT_name i denti fi ers are f orm ed bychangingall charactersotherthan letters and digits 
into underscores. 

Lines that begin with an exclamation mark (i) areignored and may beused ascomments. 

N otethat si ncexrdb can readfrom standard input, itean beused to changethecontentsof properties di rectly from a 
terminal or from ashell script. 



OPTIONS 

xrdb program accepts the following options: 
-help 

-display display 
-ali 



Thisoption (or any unsupported option) will causeabrief 
description of the allowable options and parametersto be 
printed. 

Thisoption specifiestheX server to beused; seex(l). Italso 
speci fi es thescreen to usefor the -screen option, and it 
speci fi es thescreen from which preprocessor symbolsare 
derived for the -giobai option. 

Thisoption indicates that operation should beperformed on 
thescreen-independent resource property (resource_manager), 
aswell asthe screen-specific property (screen_resources) on 
every screen of thedisplay. Forexample, when used in 
conjunction with -query, the contents of ali properties are 

Output. For -load, -override, and -merge, the input file ÌS 

processed once for each screen. The resources that occur in 
common in the output for every screen are collected, andthese 
areapplied asthe screen-independent resources. The 
remaining resourcesareapplied for each individuai per-screen 
property. This the default mode of operation. 
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Thisoption indicate thattheoperation should only be 
performed on thescreen-independentREsouRCE_MANAGER 
property. 

Thisoption indicate thattheoperation should only be 
performed on the screen_resources property of the default 
screen of thedisplay. 

Thisoption indicate that the operati on should be performed 
on the screen_resources property of each screen of thedisplay. 
For -ioad, -override, and -merge, the input fi le is processed for 
each screen. 

Thisoption indicate that changesto thespecified propertie 
(when used with -ioad, -override, or -merge) or to the resource 
fi le (when used with -edit) should beshown on the standard 
output, but should not be performed. 
Thisoption indicate that warning about duplicate entri es 
should not bedisplayed. 

Thisoption specifie the pattinarne of theC preprocessor 
program to beused. Although xrdb wasdeigned to use CPP, 
any program thatactsasafilter and acceptsthe-D, -i.and -u 
optionsmay beused. 

Thisoption indicate that xrdb should not run the input file 
through a preprocessor before loadi ng it into propertie. 
T his option indicate that the symbols that are defined for the 
preprocessor should be pri nted onto the standard output. 
T his option indicate that the current contents of the speci fi ed 
propertie should beprinted onto the standard output. N ote 
that since preprocessor commands in the input reourcefileare 
part of the input file, not part of the property, they won't 
appear in the output from thisoption. The -edit option can 
beused to merge the contents of propertie back into the input 
reource fi le without damagi ng preprocessor commands. 
Thisoption indicate that the input should beloaded asthe 
new valueof thespecified propertie, replacingwhateverwas 
there; that is, theold contents are removed. T his is the default 
action. 

Thisoption indicate that the input should beaddedto, 
instead of replacing, the current contents of thespecified 
propertie. N ew entri e override previ ous entri e. 
Thisoption indicate that the input should bemerged and 
lexicographically sorted with, instead of replacing, the current 
contents of thespecified propertie 
Thisoption indicate that thespecified propertie should be 
removed from the server. 

Thisoption indicatesthat the server should beinstructed not 
to reset if xrdb isthefirst client. T his should never benecessary 
under normal conditions, sincexdm and xinit alwaysact asthe 
first client. 

T his option indicate that the contents of the specified 
propertie should beedited into thegiven file, replacing any 
vai ue al ready listed there. T his ali owsyou to put changethat 
you have madeto your defaults back into your reource fi le, 
preserving any comments or preprocessor line. 
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-backup stri n g T his option specifies a suffix to be appended to the filmarne 

used with -edit to generate a backup file. 
-Dna me [ =v a i ue] T his option ispassed through to the preprocessor and isused 

to definesymbolsforusewith conditionalssuch as#ifdef. 
-una me Thisoption ispassed through to the preprocessor and isused 

to remo ve an y def i n i t i o n s of th i s sym bo I . 
-idi rectory Thisoption ispassed through to the preprocessor and isused 

to specify a directory to search for filestnat are referenced with 

#include. 

FILES 

Generalizes-/.xdefauits files 
SEEALSO 

x{l), X li b ResourceM anagerdocumentation, xt resourcedocumentation 
ENVIRONMENT 

display To figure outwhich display to use. 

BUGS 

The default for no argumentsshould beto query, not to overwrite, so that it isconsistent with other programs. 
AUTHORS 

Bob Scheifler and Phil Karlton, rewritten from theoriginal byjim Gettys 
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xref resti— Refresh ali or part of an X screen 
SYNOPSIS 

xrefresh [ -option . . . ] 

DESCRIPTION 

xrefresh isasimpleX program that causes ali or part of your screen to berepainted. Thisisuseful when system messages 
havemessed up your screen. xrefresh mapsawindow on top of the desi red area of the screen and then immediately unmaps 
it, causi ng refresh eventsto besent to ali applicati ons. By default, awindow with no background isused, causi ng ali 
applicationsto repaint smoothly. H owever, thevariousoptionscan beused to indicate that asolid background (of any color) 
ortherootwindow background should beused instead. 

ARGUMENTS 

-white U se a white background. T he screen just appearsto flash 

quickly, and then repaint. 

-biack Useablack background (in effect, turningoff ali of the 

electron gunsto thetube). Thiscan besomewhatdisorienting 
as everythi ng goes black for a moment. 

-soiid color U se asolid background of the specified color. Try green. 

-root U se the root wi ndow background. 



-none 

-geometry WxH+X+Y 
-display di spi ay 
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This is the default. Ali of the Windows si mply repaint. 
Specifiestheportion of thescreen to be repainted; seex(l). 
Thisargument allowsyou to specify the server and screen to 
refresh; seex(l). 



XDEFAULTS 

Thexrefresh program usestheroutinexGetDefauitox) to read defaults, so itsresourcenamesareall capitalized. 
Biack, white, soiid, None, Root D etermi nes what sortof window background to use 

Geometry D etermi nes the area to refresh. N ot very useful. 

ENVIRONMENT 

display To get default host and display number. 

SEEALSO 

x(D 

BUGS 

It should have just one default type for the background. 
AUTHORS 

Jim Gettys(D igital EquipmentCorporation, M IT Project Athena) 
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xserver— X W indow System display server 
SYNOPSIS 

X [option . . . ] 

DESCRIVO N 

x isthe generic namefortheX Window System display server. 1 1 is frequently a link or a copy of the appropriate server 
binary for driving the most frequently used server on agiven machine. 

STARTING THE SERVER 

Thex server isusually started from theX Display M anager program xdm(l). This utility isrun from the system boot filesand 
takescareof keeping the server running, promptingforusernamesand passwords, andstartinguptheusersessions. 

Installationsthat run morethan onewindow system may need to usethexinit(l) utility instead of xdm. H owever, xinit isto 
beconsidered a tool for building startup scripts and isnot intended for use by end users. Site administrators are strongly 
urged to use xdm, or build other interfacesfor novi ce users. 

Thex server may also be started di rectly by the user, though thismethod isusually reserved for testi ng and isnot recom- 
mended for normal operation. On someplatforms, the user must have special permission to start thex server, often because 
access to certain devices. (Forexample, /dev/mouse is restri cted.) 

When thex server startsup, it typically takes over the display. If you are running on a workstation whose console isthe 
display, you may not beableto log into theconsolewhiletheserver isrunning. 
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OPTIONS 

A 1 1 of th e x servers accept thefollowingcommand-lineoptions: 



: di spi aynumber 



-a n u mbe r 



-audit I evel 



-auth authorization-file 



bc 



-bs 



c voi u me 
-ce class 



-co f il e n a me 



-config fi I e ri a me 



-dpi resolution 



-def erglyphs wh i c hf ont s 



-f voi u me 
-fc cur s or Font 
-f n font 



Thex server runsasthegiven di spi aynumber , which by default 
is 0. If multi plex servers areto run simultaneously on a host, 
each must have a unique display number. Seethe"D isplay 
N ames" subsection of thex(l) manual pagete learn how to 
speci fy which display number clients should try to use. 
Sets pointer acceleration (that is, the ratio of how much is 
reported to how much theuser actually moved the pointer). 
D isables host-based access control mechanisms. Enables access 
by any host, and permits any host to modify the access control 
list. Usewith extremecaution.Thisoption exists primari lyfor 
ru n n i n g test su i tes rem otd y . 

Sets the audit trai I level. The default level isl, meaningonly 
connection rejections are reported. Level 2 additionally reports 
ali successful connectionsand disconneets. Level Oturnsoff 
the audit trai I. Audit linesaresent as standard errar output. 
Specifies a file which contai ns a collection of authorization 
recordsused to autenticate access. Seealso thexdm and 
xsecurity manual pages. 

D isables certain kindsof errar checking, for bug compati bility 
with previ ousreleases (for example, to work around bugs in 
R2 and R3 xterms and toolkits). D eprecated. 
D isables backing store support on ali screens. 
Turnsoff key-click. 

Sets key-click volume (allowable range 0-100). 
Sets the visual class for the root wi ndow of color screens T he 
class numbers are asspecified in thex protocol. N ot obeyed by 
ali servers. 

Sets nameof RGB color database. The default is<xRoot>/iib/ 
xn/rgb, where<xroot> refersto the root of the X 11 instali 
tree 

Readsmoreoptionsfrom thegiven file. Optionsin thefile 
may be separated by newlinesif desired. If a # character 
appears on a line, ali characters between it and the next 
newlineareignored, provi di ng a si mple commenti ng faci li ty. 
The -config option itself may appear in thefile. 
C auses the server to generate a core dum p on fatai errors. 
Sets the resolution of thescreen, in dots per inch. To beused 
when theserver cannot determinethescreen sizefrom the 
hardware 

Specifies the typesof fontsforwhich theserver should attempt 
to usedeferred glyph loading. whi chfonts can beau (ali fonts), 
none (no fonts), or 16 (16-bit fonts only). 
Setsfeep (beli) volume(allowable range: 0-100). 
Sets default cursor font. 
Sets the default font. 
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-fp f ont Pat h 



-I 
-kb 

-p mi n u t e s 
-pn 



-s mi n ut es 
-su 

-t n u mbe r 

-terminate 

-to seconds 
-tst 

ttyxx 
v 

-v 
-wm 



FI 



-x extensi on 



Sets the search path for fonts. Thispath isa comma-separated 
list of di rectories that the X server searches for font databases. 
-heip pri nts a usage message. 

C auses al I rem ai n i n g com m and- 1 i n e argu m ents to be i gn ored . 

D isables the xkeyboard extension if present. 

Sets screen saver pattern cycle ti me i n mi nutes. 

Permits the server to continue running if it failsto establish ali 

of itswell-known sockets (connection pointsforclients), but 

estabi ishesatl eastone. 

Turnsoff auto-repeat. 

Turnson auto-repeat. 

Sets screen saver ti me-out ti me in mi nutes. 

D isables saveunder support on ali screens. 

Sets pointer acceleration threshold in pixels (that is, sets after 

how many pixels pointer acceleration should takeeffect). 

C auses the server to terminate at server reset, instead of 

conti nuing to run. 

Sets default connection time-out in seconds. 

D isables ali testing extensions (for example, xtest, xmap, 

XTestExtensionl). 

Ignored, forserversstartedtheancientway(from init). 
Sets video-off screen saver preference. 
Setsvideo-on screen saver preference 
Forces the default backing-storeof ali Windows to bewnen- 
Mapped. T his is a backdoor way of getti ng backi ng-store to 
applyto ali Windows. Although ali mapped Windows will have 
backi ng-store, the backi ng-store attribute value reported by the 
server for a window will be the last value established by a 
client. If it hasnever been set by aclient, the server will report 
the default value, Notusefui. Thisbehavior isrequired bythe 
x protocol, which allows the server to exceed theclient's 
backing-store expectations but does not provide a way to teli 
theclientthat it isdoingso. 

Loadsthespecified extension at init. Thisisano-op for most 
impietri entations. 



SERVER DEPENDENT OPTIONS 

Some x servers accept th e f o 1 1 owi n g o pti o n s: 

-ld ki I obyt es 



-lf f i I es 



-ls ki I obyt es 



Sets the data space limit of the server to the specified number 
of ki lobytes. A value of zero makes the data size as large as 
possi ble The default value of -1 leavesthedataspacelimit 
unchanged. 

Sets the number-of-open-files limit of the server to the 
specified number. A valueofzero makes the limit as large as 
possi ble. The default value of-1 leavesthe limit unchanged. 
Sets the stack space limit of the server to th e speci f i ed n u m ber 
of ki lobytes. A value of zero makes the stack size aslarge as 
possi ble. T he default value of -1 leaves the stack space limit 
unchanged. 
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-ìogo Turnson theX Window System logo display in thescreen 

saver. Thereis cu rrently no wayto changethisfrom aclient. 

noiogo Turnsoff the X Window System logo display in thescreen 

saver. Thereis currently no wayto changethisfrom aclient. 

XDMCPOPTIONS 

x serversthat supportXD M CP havethefollowing options. (SeetheX Display M anager Control Protocol specification for 
more informati on.) 

-query host-name E nable X D M C P and send Query packets to the specified host. 

-broadcast EnableXDM CP and broadcast BroadcastQuery packetstothe 

network. T he fi rst respondi ng display manager wi II be chosen 

forthesession. 

-indirect host-name E nable X D M C P and send mdirectQuery packets to the 

specified host. 

-port po r t - n u m U se an alternate port num ber for X D M C P packets. M ust be 

specified beforeany -query, -broadcast, or -indirect options. 

-class display-class XD M CP hasan additional display qualifierused in resource 

lookup for display-specific options. This option sets that value; 
by default it isMiT-unspecified (not a very useful value). 

-cookie xdm-autn-bits W hen testi ng xdm-authentication-1, a private key is sharexd 

between the server and the manager. This option sets the value 
of that private data (not that it isvery private, being on the 
command line!). 

-dispiayiD display -id Yet another XD M C P-specific value, this oneallows the display 

manager to identify each display so that it can locate the 
shared key. 

XKEYBOARD OPTIONS 

x serversthat support the xkeyboard extension accept thefollowing options: 

-xkbdir directory Base directory for keyboard layout files 

-xkbmap fi i e ri a me K eyboard descri pti on to load on startup 

[ + -]accessx Enable(+) or disable(-) AccessX keysequences 

-an mi 1 1 i seconds Sets the length of ti me in milliseconds that a key must be 

depressed beforeauto-repeat starts 
-ar2 mi 1 1 i seconds Sets the length of timein milliseconds that should elapse 

between auto-repeat-generated keystrokes 

M any serversalso havedevice-specific command-li ne options Seethemanual pages for the individuai serversfor more 
details. 

NETWORK CONNECTION S 

Thex server supports client connectionsviaa platform-dependent subset of thefollowing transport types: TCPIP, UN IX 
Domain sockets, D ECnet, and several vari eties of SVR4 locai connections. Seethe"D isplay N ames" subsection of thex(l) 
manual pagete learn how to specify which transport typeclients should try to use 

SECURITY 

Thex server implements a platform-dependent subset of thefollowing authorization protocols: -mit-magiccookie-1, xdm- 
authorization-1, sun -DES- 1 , and mit-kerberos-5. See the xsecurity(l) manual page for information on theoperation of these 
protocols. 
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Authorization data required by the precedi ng protocols ispassed to the server in a private fi le nam ed with the-auth 
command-lineoption. Each ti me the server isabout to accept the first connection after a reset (or when the server is 
starti ng), it readsthisfile. Ifthis fi le contai nsany authorization records, the locai host isnot automati cally allowed access to 
the server, and only clientsthat send oneof the authorization records contai ned in the fi le in the connection setup informa- 
tion will be allowed access. Seethexau manual pageforadescription of the binary format ofthisfile. Seexauth(l) for 
maintenanceof thisfile and distri bution of itscontentsto remotehosts. 

The xserver also usesa host-based access control list for decidi ngwhether or not to accept connectionsfrom clientson a 
parti cular machine If no other authorization mechanism isbeingused, thislist initially consistsof thehost on which the 
server isrunningaswell asany machi nes listed in the fi le /etc/xn .hosts, wheren is the display number of the server. Each 
lineof thefileshould contai n eitheran Internet hostname (for exampleexpo.ics.mit.edu) or a D ECnet hostnamein doublé 
colon format (for example, hydra: :).Thereshould beno leading ortrailingspaceson any li nes. For example, 

joesworkstation 
corporate.company.com 
star: : 
bigcpu: : 

Userscan add or remove hosts from this list and enableor disable access control usingthexnost command from thesame 
machine as the server. 

Thex protocol intrinsi cally doesnot haveany notion of window operation permissionsor place any restri ctionson what a 
client can do; if a program can connect to a display, it hasfull run of thescreen. Sitesthat havebetter authentication and 
authorization systemsmightwish to makeuseof thehooksin thelibrariesand the server to provide additi onal security 
model s. 

SIGNALS 

Thex server attaches special meaning to thefollowing signals: 

sighup Thissignal causes the server to dose ali existingconnections, 

freeall resources, and restare ali defaults. It issent by the 
display manager whenever the main user'smain application 
(usually an xterm or window manager) exitsto force the server 
to clean up and prepare for the next user. 

sigterm Thissignal causes the server to exit cleanly. 

siGusRi Thissignal isused quite differently from either of theabove. 

W hen the server starts, it checks to see if it has i nherited 
siGusRi assiG_iGN instead of the usuai sig_dfl. In this case, 
the server sends a sigusri to its parent process after it has set 
up the various connection schemes. xdm usesthisfeatureto 
recognizewhen connectingto the server ispossible 

FONTS 

Thex server can obtain fontsfrom directoriesor from font servers. The list of directoriesand font serversthex server uses 
when tryingto open a font is controlied bythefont path. 

The default font path is 

<XRoot>/lib/X1 1 /f onts/misc/ , 
<XRoot>/lib/X1 1 If onts/Speedo/ , 
<XRoot>/lib/X1 1 If onts/Typel / , 
<XRoot>/lib/X1 1 If onts/75dpi/ , 
<XRoot>/lib/X11/fonts/100dpi/ 

where <xRoot> refersto theroot of theXll instali tree. 



Thefont path can be set with the-tp option or by xset(l) after the server hasstarted. 
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FILES 



/etc/Xn .hosts 

<XRoot>/lib/X1 1/fonts/misc 
<XRoot>/lib/X1 1 /f onts/75dpi 
<XRoot>/lib/X1 1 /f onts/100dpi 
<XRoot>/lib/X1 1 /f onts/Speedo 
<XRoot>/lib/X1 1 /f onts/Typel 
<XRoot>/lib/X1 1 /f onts/PEX 
<XRoot>/lib/X11/rgb.txt 
/trap/.X11 -unix/Xn 
/tmp/rcXn 
/usr/adm/Xnmsgs 

<XRoot>/lib/X1 1 /xdm/xdm-errors 



Initial access control list for display numbern 



Bitmap font di recto ri es 

0 utl ine font di rectories 
PEX font di rectories 
Color database 

UNIX domain socket for display number n 
Kerberos5 replay cachefor display number n 
Errorlogfilefor display numbern if run from init(8) 
Default errar log file if the server isrun from xdm(l) 



Note: <xRoot> refersto theroot of the X 11 instali tree. 

SEEALSO 

General information: x(l) 

Protocols: X Window System Protocol, TheX Font Service Protocol, X Display Manager Control Protocol 
Fonts bdftopcf(l), mkfontdir(l), xfs(l), xisfonts(l), xfontsei(l), xtd(l), X Logicai Font D escription Conventions 

Security: Xsecurity(l), xauth(l), xau(l), xdm(l), xhost(l) 

Starting the server: xdm(l), xinit(l) 

C ontrolling the server oncestarted: xset(l), xsetroot(l), xhost(l) 

Server- SpecifiC man pages: Xdec(l), Xmacll(l), Xsun(l), Xnest(l), Xvfb(l), XF86 Accel(l), XF86 Mono(l), XF86 SVGA(l), XF86 
VGA16(1), XFree86(l) 

Server internai documentati on: "D efiniti on of the Porti ng Layer for theX vii Sam pi e Server," "Strategies for Porti ng the X 
vii Sample Server," "Godzilla'sGuideto Porting theX vii SampleServer" 

AUTHORS 

T he sample server wasoriginally written by Susan Angebranndt, Raymond D rewry, Philip Karlton, and Todd N ewman, 
from D igital Equi pment Corporation, with support from a large cast. It hassincebeen extensively rewritten by Keith 
Packard and Bob Scha'fler, from M IT. 
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xset— User preference utility for X 
SYNOPSIS 

xset [-display display] [-b] [b on/off] [b [volume [pitch [duration]]] [[-]bc] 
[-c] [c on/off] [c [volume]] [[-+]fp[-+=] pat h [ , p a t h [,...]] ] [fp default] 
[fp rehash] [[-]led [integer]] [led on/off] [m[ouse] [a c c el _ mu 1 1 [ /a c c el _ d i v ] 
[threshol d ]]] [m[ouse] default] [p pixel color] [[-]r [keycode]] [r on/off] 
[s [length [peri od]]] [s blank/noblank] [s expose/noexpose] [s on/off] 
[s default] [s activate] [s reset] [q] 
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DESCRIVO N 

This program isused to set vari ous user preference opti onsof the di splay. 



OPTIONS 

-display display 
b 



bc 



fp= p a t h , . . 

fp default 
fp rehash 

-fp or fp- 



Thisoption speci fi es the server to use; seex(l). 
Theb option controis beli volume, pitch, and duration. This 
option acceptsup to three numerical parameters, a precedi ng 
dash (-), or an on/off flag. If no parameters are given, or theon 
flag isused, the system defaults wi II beused. If the dash or off 
is given, the beli will beturned off. If only one numerical 
parameter is given, the beli volumewill be setto that value, as 
a percentageof its maximum. Likewise, thesecond numerical 
parameter specifies the beli pitch, in hertz, andthethird 
numerical parameter specifies the duration in milliseconds. 
Note that notali hardware can vary the beli characteristics. 
T he x server will set thecharacteristicsof the beli as closely as 
it can to the user's specifications. 
Thebc option controlsbug compatibility modein the server, 
if possi ble; a precedi ng dash (-) disables the mode otherwise, 
the mode is enabled. Various pre-R4 clients pass i llegal values 
in some protocol requests, and pre-R4 serversdid notcorrectly 
generate errors in thesecases. Such clients, when run against 
an R4 server, will terminate abnormally or otherwise fail to 
operate co rrectly. Bug compatibility modeexplicitly reintro- 
ducescertain bugs into thex server, so that many such clients 
can stili berun. This mode should beused with care new 
application development should bedonewith thismode 
disabled. The server must support the mit-sundry- nonstandard 
protocol extension in orderfor this option towork. 
Thec option controlskey click. This option can takean 
optional value, a precedi ng dash (-), or an on/off flag. If no 
parameter or theon flag is given, the system defaults will be 
used. If the dash or off flag isused, key click will be disabled. 
If a value from 0 to 100 is given, it isused to indicate volume, 
as a percentage of the maximum. Thex server will set the 
volume to thenearest value that the hardware can support. 
Thefp= sets the font path to the entri es given in thepath 
argument. T h e en tri es are i n terp reted bytheserver, not bythe 
client. Typically, they are directory namesor font server 
names, but the interpretati on isserver-dependent. 
The default argument causes the font path to be reset to the 
server's default. 

The rehash argument resets the font path to its current value, 
causi ng the server to reread the font databases in the current 
font path. This is generally only used when adding new fonts 
to a font directory (after runni ng mkf ontdir to recreate the 
font database). 

The-fp and fp- options remove elements from the current 
font path. They must befollowed by acomma-separated list of 
entri es. 
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tp or tp 



led 



ni 



P 



r 



Thistp and tp optionsprepend and append elementsto the 
currentfont patti, respectively. They must befollowed by a 
comma-separated list of entries. 

The led option controlsthekeyboard leds. Thiscontrolsthe 
turningon or off of oneor ali ofthei_EDS. Itacceptsan 
optional integer, apreceding dash (-) or an on/off flag. If no 
parameter ortheon flag isgiven, ali leds are turned on. If a 
preceding dash or the flag off isgiven, ali leds are turned off. 
If a valuebetween 1 and 32 isgiven, that ledwìII be turned 
on or off dependi ng on the exi stence of a precedi ng dash. A 
common led that can be controlied isthecaps Lock led. xset 
ied 3 would turn led #3 on. xset -led 3 would turn it off. 
The parti cular led values may refer to different leds on 
different hardware. 

T he m opti on controis the mouse parameters. The parameters 
for the mouse are acceieration and threshoid. T he accelera- 
tion can bespecified asan integer, orasasimplefraction.The 
mouse, orwhatever pointer the machine isconnected to, will 
go acceleratici ti mes as fast when ittravelsmorethan 
threshoid pixelsin ashorttime Thisway, the mouse can be 
used for precise alignment when it ismoved slowly, yet it can 
be setto travel acrossthescreen in aflick of the wrist when 
desired. Oneor both parameters for the m option can be 
omitted, butif only one isgiven, itwill beinterpreted asthe 
acceleration. If no parameters or the flag default isused, the 
system defaultswill beset. 

The p option controis pixel color values. The parameters are 
thecolor map entry number in decimai, and a color speci fi ca- 
tion. Theroot background colorsmay bechanged on some 
servers by alteri ng the entries for BiackPixei and whitePixei. 
Although theseareoften 0 and 1, they need not be. Also, a 
server may chooseto allocate thosecolors privately, in which 
casean errar will begenerated. The map entry must not bea 
read-only color, oran errar will result. 
Ther-option controlstheauto-repeat. If a preceding dash 
or the off flag isused, auto-repeat will bedisabled. If no 
parameters ortheon flag isused, auto-repeat will beenabled. 
If a specific keycode is specified as a parameter, auto-repeat 
for that keycodeisenabled ordisabled. 
Thes option letsyou setthescreen saver parameters This 
option accepts up to two numerical parameters, a biank/ 
noblank flag, an expose/noexpose flag, an on/off flag, an 
activate/reset flag, or the default flag. If no parameters or 
the defauit flag isused, the system will be setto its default 
screen saver characteristics. The on/off flagssimply turn the 
screen saver functionson or off. Theactivateflagforces 
activation of screen saver even if the screen saver had been 
turned off. The reset flagforcesdeactivation of screen saver 
if it isactive. Thebiank flag sets the preferen ceto blank the 
video (if the hardware can do so) rather than display a 
background pattern, whilenobiank sets the preferenceto 
display a pattern rather than blank the video. The expose flag 
sets the preferenceto allow wi ndow exposures (the server can 
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freely discard window contents), whilenoexpose setsthe 
preferenceto disablescreen saver unless the server can 
regen erate the screen s wi th out causi n g exposu re events. The 
ìength and period parameters for the screen saver function 
determi nes how long the server must beinactivefor screen 
saving to activate, and the period to changethe background 
pattern to avoid bum in. Theargumentsarespecified in 
seconds. If only onenumerical parameter isgiven, itwill be 
used forthelength. 

q Theq option givesyou information on the current setti ngs. 

Thesesettingswill be resetto default valueswhen you log out. 

N otethat not ali x implementationsareguaranteed to honor ali of theseoptions. 

SEEALSO 

x(l), Xserver(l), xmodmap(l), xrdb(l), xsetroot(l) 

AUTHOR 

Bob Scheifler (M IT Laboratory for Computer Science), David Krikorian (M IT Project Athena; X 11 version) 
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xsetroot— Rootwindow parameter setting utility forx 
SYNOPSIS 

xsetroot [-help] [-def] [-display display] [-cursor cursorfile maskfile] 
[ -cursor_name cursorname] [-bitmap fi I e n a me ] [-mod x y] [-gray] [-grey] 
[-fg color] [-bg color] [-rv] [ -solid col or ] [ -name stri n g ] 

DESCRIPTION 

Thesetroot program allowsyou to tailortheappearanceof the background (root) window on aworkstation display running 
x. N ormai ly, you experi mentwith xsetroot until you find a personal ized look that you like, then put the xsetroot command 
that producesit into your x startup file. If no optionsare specified, or if -def isspecified, the window is reset to its default 
state. The -def option can be specified along with other optionsand only thenonspecified characteri stics wi 1 1 be resetto the 
default state. 

Onlyoneof the background color/tiling changing options {-solici, -gray, -grey, -bitmap, and -mod) may be specified at a 
ti me. 

OPTIONS 

T h e vari ous o pti o n s are as f o 1 1 ows: 
-help 
-def 



-cursor cursorfile ma s kf i I e 



Printausagemessageand exit. 

Reset unspecified attri butes to the default values. (Restoresthe 
background to the fami li ar gray mesh and the cursor to the 
hollowxshape) 

T his lets you change the poi nter cursor to whatever you want 
when the pointer cursor isoutside of any window. Cursor and 
mask files are bitmaps (little pictures), and can bemadewith 
thebitmap(l) program. You probably want the mask fileto be 
ali black until you get used to theway maskswork. 
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-cursor name c u r s or na me 



-bitmap fi I e ri a me 



-mod x y 



-gray 
-grey 
-fg color 



-bg col or 



-solici col or 



-name strina 



-display display 

SEEALSO 

x(l), xset(l), xrdb(l) 

AUTHOR 

M ark L i Ili bridge (M IT Project Athena) 



T his lets you change the poi nter cursor to one of the standard 
cursorsfrom the cursor font. Referto AppendixB ofthex 
protocol forthenames(except that thexc prefix iselided for 
thisoption). 

Use the bitmap specified in thefileto set thewindow pattern. 
You can makeyour own bitmap files(littlepictures) usi ng the 
bitmap(l) program. The enti re background will bemadeupof 
repeated "tiles" of the bitmap. 
Thisisused if you want a piai d-li ke grid pattern on your 
screen. x and y are integers ranging from 1 to 16. Try the 
different combinations. Zero and negative numbers are taken 
asl. 

M ake the enti re background gray. (Easieron theeyes.) 
M ake the enti re background grey. 
Usecoi or astheforeground color. Foreground and back- 
ground colorsaremeaningful only in combination with 

-cursor, -bitmap, Or -mod. 

Usecoior as the background color. 
T his exchanges the foreground and background colors. 
N ormally theforeground color is black and the background 
color iswhite. 

T his sets the background of therootwindow to the specified 

color. Thisoption isonlyuseful on color servers. 

Set the name of therootwindow to st ri ng. There isno default 

value. U sually a name is assi gned to awindow so that the 

window manager can use a text representation when the 

window isiconified. Thisoption isunused becauseyou can't 

iconify the background. 

Specifies the server to connectto; seex(l). 
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xsm—x Sessi on Manager 
SYNOPSIS 

xsm [ -display di s pi ay ] [ -session s es s i o n Na me ] [-verbose] 

D ESC RIPTIO N 

xsm is a session manager. A session isa group of applications, each of which hasa parti cular state, xsm allowsyou to create 
arbitrary sessions. Forexample, you might haveangnt session, adeveiopment session, or an xterminai session. Each session 
can haveitsown set of applications. W ithin a session, you can perform acneckpoint to save application state, or ashutdown 
to save state and exit the session. W hen you log back in to the system, you can load a specific session, and you can delete 
sessions you no longerwantto keep. 
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Somesession managerssimply allow you to manually speci fy a list of applicationsto bestarted in a sessi on. xsm ismore 
powerful becauseit letsyou run applicationsand havethem automati cai ly becomepartof the sessi on. On asimplelevd, xsm 
isuseful becauseit givesyou this ability to easi ly define which applicationsarein asession.Thetruepowerof xsm, however, 
can betaken advantage of when more and more appi ications learn to saveand restoretheir state. 

OPTIONS 

-display display 
-session sessi onName 

-verbose 

SETUP 

.xsession FILE 

Using xsm requiresachangetoyour .xsession file 

Thelast program executed by your .xsession fileshould bexsm. W ith this confi guration, when the user choosesto shut 
down thesession using xsm, thesession will truly beover. 

B ecause the goal of thesession manager isto restart clientswhen logging into a session, your .xsession file, in general, should 
not directly start up appi ications. Rather, the appi ications should bestarted within a session. When xsm shutsdown the 
session, xsm will know to restart these applicati ons. N ote, however, that there are some typesof applicati onsthat are not 
"session aware". xsm enablesyou to manually add these applicationsto your session. (Seethesubsection titled "Client List.") 

SM_SAVE_D I R EN VI RO N M EN T VARI ABLE 

If the sm_save_dir envi ronment vari able is defined, xsm will saveall configuration filesin this directory. Otherwise, they will 
bestored in the user's home directory. Session-aware applicati ons are also encouraged to savetheir checkpoint filesin the 
sm_save_dir directory, although the user should not depend on this convention. 

DEFAULTSTARTUP APPLICATIONS 

The first ti me xsm isstarted, it will need to locate a list of applicationsto start up. For example, this list mi ght include a 
window manager, a session management proxy, and an xterm. xsm will first look for the file .xsmstartup in the user's home 
directory. If that file does not exist, it will look for the system, xsm fi le that wasset up at installati on ti me. N ote that xsm 
providesataiisafe option when the user chooses a session to start up. Thefaiisafe option simply loads the default 
appli cati ons descri bed above. 

Each line in the startup fileshould contain a command to startan application. A samplestartup filemight look this: 

<start of file> 
twm 

smproxy 
xterm 

<end of file> 

STARTING A SESSION 

When xsm startsup, it first checksto seeif the user previ ously saved any sessions. If no saved sessions exist, xsm startsup a set 
of default applications (as descri bed above in thesubsection titled "Default Startup Applications"). If at leastone session 
exists, aSession menu ispresented. The[ -session sessionName] option forces the specified session to beloaded, bypassing 
thesession menu. 

THESESSION MENU 

The Session menu presents the user with a list of sessi ons to choosefrom. The user can changethecurrently selected session 
with the mouse, or by using the up and down arrowson thekeyboard. N ote that sessions that are locked (that is, runningon 
a different display) cannot beloaded ordeleted. 



Causesxsm to connectto the specified X display. 
Causesxsm to load the specified session, bypassing the session 
menu. 

Turnson debugging information. 
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Thefollowingoperationscan be performed from theSession menu: 

Load Session Pressing this button will load thecurrently selected session. 

Alternative! y, hitting the Return key will also load the 
currently selected session, or the user can double-click a session 
from the list. 

DeleteSession Thisoperation will delete the currently selected session, along 

with ali of the application checkpoi nt files associateci with the 
sessi o n . After pressi n g th i s butto n , th e user w i 1 1 be asked to 
press the button a secondarne in orderto confi rm the 
operation. 

D efault/Fai I Safe xsm will start up a set of default applications (asdescri bed 

earlier in thesection titled "Default Startup Applications"). 
Thisisuseful when the user wantsto start afresh session, or if 
the session confi guration files were corrupted and the user 
wantsafailsafe session. 

Cancel Pressing this button will cause xsm to exit. It can also beused 

to cancel a Delete Session operation. 

CONTROLLING A SESSION 

After xsm determi neswhi eh session to load, it bringsup its main window, then startsup ali applications that arepart of the 
session. Thetitlebar for the session manager's main window will contai n the nameof the session thatwasloaded. 

Thefollowing options are available from xsm's main window: 

C lient List Pressing this button brings up a window containing a list of ali 

clients that arein thecurrent session. Foreach client, thehost 
machine that the client isrunningon ispresented. As clients 
areadded and removed from thesession, th i s I i st isupdated 
to reflect the changes. The user isableto control howthese 
clients are restarted. 

By pressing the View Properties button, the user can view the 
session management properties associ ated with thecurrently 
selected client. 

By pressing the Clone button, the user can start a copy of the 
selected application. 

By pressing the K ili Client button, theuser can removea client 
from the sessi on. By selecting a restart h i nt from the R estart 
H int menu, theuser can control the restarti ngof a client. The 
following hi nts are available: 

■ TheRestart If Running hint indicatesthattheclient 
should be restarted in thenext session if it isconnected to 
thesession manager at the end of thecurrent session. 

■ TheRestart Anyway hint indicatesthattheclient should 
be restarted in the next session even if it exits beforethe 
current session isterminated. 

■ TheRestart Immediately hint issi mi larto the Restart 
Anyway hint, but in addition, theclient ismeantto run 
continuously. If the client exits, thesession manager will 
try to restart it in thecurrent session. 

■ TheRestart N ever hint indicatesthattheclient should not 
be restarted in the next session. 
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N otethat ali X applicationsmay not besession aware. 
Applicationsthat are not session aware are onesthat do not 
support theX Session M anagement Protocol or they cannot 
bedetected by theSession M anagement Proxy. (Seethe 
subsection ti ti ed "TheProxy."). xsm allowstheuserto 
manually add such applicationsto the session. Thebottom of 
the C lient List wi ndow contai ns a text entry f i d d i nto wh i eh 
application commandscan betyped. Each command should 
go on itsown line. This informati on will besaved with the 
session atcheckpointorshutdown time. When thesession is 
restarted, xsm will restart these applicati ons in addi ti on to the 
regular session aware applications. Pressing the Donebutton 
removestheClient Listwindow. 

Session Log... TheSession Logwindow presentsuseful information about 

thesession. Forexample, when a session is restarted, ali of the 
restart commandswill bedisplayed in the logwindow. 

Checkpoint By performing a checkpoint, ali applicationsthat are in the 

session areasked to savetheir state. N ot every application will 
saveits complete state, butat a minimum, thesession manager 
isguaranteed that itwill recei ve the command required to 
restart theapplication (along with ali command-lineoptions). 
A window manager parti ci pati ng in thesession should 
guarantee that the applications will come back up with the 
samewindow configurations 

If thesession being checkpointed was never assigned a name, 
the user will be required to specify a session name. Otherwise, 
the user can perform the checkpoint usi ng the current session 
name, oranew session name can bespecified. If thesession 
namespecified al ready exists, theuserwill begiven the 
opportunity to specify a different name or to overwrite the 
al ready existing session. N otethat a session that is locked can 
not be overwritten. 

When performing a checkpoint, the user must specify a save 
Type thatinformstheapplicationsin thesession how much 
state they should save. 

The Locai type indicates that the application should save 
enough information to restare the state asseen by the user. It 
should not affect the state as seen by other users. For example, 
an editorwould create a temporary filecontaining thecontents 
ofits editing buffer, the location of thecursor, and so on. 
The Giobai type indicates that theapplication should commit 
ali ofits datato permanent, globally accessible Storage. For 
example, theeditorwould simply savetheedited file. 
TheBoth type indicates that the application should do both of 
these. For example, theeditorwould savetheedited file, then 
create a temporary fi le with information such as the location of 
thecursor, and so on. 

In addition to the save Type, the user must specify an mteract 
Style. 

TheNone type indicates that the application should not 
interact with the user while saving state. 
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The Emors type i ndicates that the appli cati on may i nteract 
with the user only if an errar condition arises. 
TheAny type i ndicates that the application may i nteract with 
theuser for any purpose N otethat xsm will only allow one 
application to interact with theuser at a time. 
After the checkpoint is compieteci, xsm will, if necessary, 
display a window contai ni ng the list of appli cati ons that did 
not report a successful save of state. 
Shutdown A shutdown provides ali of the opti ons found in a checkpoint, 

but, in addition, can cause the sessi on to exit. N otethat if the 
interaction styleis Emors or Any, theuser may cancel the 
shutdown. Theuser may also cancel the shutdown if any of 
the applications report an unsuccessful save of state. Theuser 
may chooseto shut down thesession with or without 
perforai ing a checkpoint. 

THE PRO XY 

Becausenot ali applications havebeen ported to support theX Sessi on M anagement Protocol, a proxy servi ce existsto enable 
"old" clientsto work with thesession manager. In order for the proxy to detect an application joininga session, one of the 
following must betrue: 

■ The application mapsatop-level window contai ni ng the wm_client_leader property. Thisproperty provi des a pointer to 
the client leader window that contai ns the wm_class, wm_name, wm^command, and wm_client_machine properties. 

or 

■ Theapplication mapsatop-level window that does not contain thewM_cLiENT_i_EADER property. H owever, thistop-level 
window contai ns the wm_class, wm_name, wm_command, and wm_client_machine properties. 

An application that supports the wm_save_yourself protocol will recei ve a wm_save_yourself client messageeach ti me the 
session manager issues a checkpoint or shutdown. This al lows the application to save state. If an application does not support 
the wm_save_yourself protocol, then theproxy will provide enough information to thesession manager to restart the 
application (usi ng wm_command), but no state will berestored. 

REMOTE APPLICATIONS 

xsm requires a remote execution protocol in order to restart appli cati ons on remote mach ines. Currently, xsm supports the 
rstart protocol. In order to restart an application on remote machineX, machineX must haverstart instai led. In the 
future additional remote execution protocolsmay besupported. 

SEE ALSO 

smproxy(l), rstart(l) 

AUTHORS 

Ralph M or (X Consortium), Jordan Brown (Quarterdeck Office Systems) 

X Versi on 11 Re!ease6 

xsmclient 

xsmciient— X session manager tester 
SYNOPSIS 

xsmclient [ TBD ] 
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DESCRIPTION 

Thexsmciient program isused to test the sessi on manager 

AUTHOR 

Ralph M or(X Consortium) 



X Versi on 11 Re!ease6 



xstdcmap 

xstdcmap— X standard colormap utility 



SYNOPSIS 

xstdcmap [-ali] [-best] [-blue] [-default] [ -delete map ] [ -display di s pi ay ] 
[-gray] [-green] [-help] [-red] [-verbose] 

DESCRIPTION 

The xstdcmap utility can beused to selectively define standard colormap properties. It isintended to berun from auser'sX 
startup script to create standard colormap definitionsin orderto facilitate shari ng of scarce colormap resources among 
cliente. W hereat ali possible, colormapsarecreated with read-only allocations. 

OPTIONS 

Thefollowing options may beused with xstdcmap: 

-ali Thisoption i ndicates that al I six standard colormap properties 

should bedefined on each screen of the display. Notali screens 
will support visuals under which ali six standard colormap 
properties are meaningful. xst-dcmap will determi ne the best 
allocations and visuals for the colormap properties of a screen. 
Any previously existing standard colormap properties will be 
replaced. 

Thisoption indicates that the rgb_best_map should bedefined. 
Thisoption indicates that the rgb_blue_map should bedefined. 
Thisoption indicates that the rgb_default_map should be 
defined. 

Thisoption specifies that a specific standard colormap 
property, orali such properties, should beremoved. map may 
beone Of: default, best, red, green, blue, gray, or ali. 
Thisoption specifies the host and display to use; seex(l). 
Thisoption indicates that the rgb_gray_map should bedefined. 
Thisoption indicates that the rgb_green_map should be 
defined. 

Thisoption indicates that a brief description of thecommand- 
li ne arguments should beprinted on thestandard errar. This 
will bedonewhenever an unhandled argument isgiven to 



-best 
-blue 
-default 

-delete map 

-display display 

-gray 

-green 

-help 



-red 

-verbose 



xstdcmap. 

Thisoption indicates that the rgb_red_map should bedefined. 
Thisoption indicates that xstdcmap should print logging 
information asit parsesi te input and defines the standard 
colormap properties. 




Parti: U ser Commands 



ENVIRONMENT 

display To get default host and display number 

SEEALSO 

x(D 

AUTHOR 

Donna Converse (M IT X Consorti um) 

X Versi on 11 ReleBse6 
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xterm— Terminal emulatorforX 
SYNOPSIS 

xterm [—tool ki topti on ...] [-option ...] 

D ESC RIPTIO N 

The xterm program is a terminal emulator for theX Window System. It providesD EC VT102- and Tektronix 4014- 
compati ble termi nals for programs that can't use the wi ndow system di recti y. I f the underlyi ng operati ng system supports 
terminal resizing capabilities(for example, thesiGwiNCH signal in systems derived from 4.3bsd), xterm will use the faci li ti esto 
notify programs running in thewindow whenever it is resized. 

TheVT102 and Tektronix 4014 termi nals ali havetheir own Windows so thatyou can edittext in oneand look at graphics 
in theother atthesametime To maintain thecorrect aspect ratio (height/width), Tektronix graphics will berestricted to the 
largest boxwith a 4014's aspect ratio that will fit in thewindow. This box islocated in theupper-left area of thewindow. 

Although both Windows may bedisplayed atthesametime, oneof them isconsidered the active window for receiving 
keyboard input and terminal output. Thisisthewindow thatcontainsthetext cursor. Theacti ve window can bechosen 
through escape sequences, theVT Options menu in the VT 102 window, and theTek Optionsmenu in the 4014 window. 

EMULATIONS 

TheVT 102 emulation isfairly complete, but does not support smooth serali ing, VT52 mode, the bl inking character 
attributenorthedouble-wideand double-size character sets. termcap(5) entriesthatworkwith xterm include xterm, vti&2, 
vtlOB, and ansi, and xterm automati callysearches the termeap file in this order for these entri es and then sets the term and the 
termcap environment variables. 

M any of the special xterm featuresmay bemodified under program control through a set of escape sequences different from 
the standard VT 102 escape sequences. (Seethe"Xterm Control Sequences" document.) 

TheTektronix4014 emulation isalso fairly good. It supports 12-bit graphics addressing, scaled to thewindow size. Four 
different font sizesand fi ve different linestypes aresupported. There isno write-through or defocused mode support. The 
Tektronix text and graphics commands are recorded internai ly by xterm and may bewritten to afileby sending the copy 
escape sequence (or through theTektronix menu, discussed later in this section). The name of the fi le will becoPYyy-MM- 
dd. hh: mm: ss, whereyy, M M , dd, hh, mm, and ss are the year, month, day, hour, minute, and second when the copy was 
performed (thefileiscreated in the directory xterm isstarted in, or the home directory for a login xterm). 

0THER FEATURES 

xterm automati cai ly highlights the text cursor when the pointer enters the window (selected) and unhighlightsitwhen the 
pointer leaves the window (unselected). If thewindow is the focus window, then the text cursor is hi ghlighted no matter 
where the pointer is. In VT102 mode, there are escape sequences to acti vate and deactivatean alternate screen buffer, which 
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is the samesizeas the display area of the window. When activated, thecurrent screen issaved and replaced with the alternate 
screen. Savingof li nes scrolled off the top of the window isdisabled until thenormal screen isrestored. Thetermcap(5) entry 
for xterm allows the visual editor vi(l) to switch to the alternate screen for editing and to restare the screen on exit. 

In either VT 102 or Tektronix mode, there are escape sequencesto change the nameof the Windows. Seexterm Control 
Sequencesfor details. 

0PTI0NS 

The xterm terminal emulator acceptsall of the standard X Toolkit command-lineoptionsaswell asthefollowing (if the 
option beginswith a + instead of a -, the opti on isrestored to its default value): 

-heip Thiscauses xterm to print out a verbose message describi ng its 

options. 

-132 N ormally, the VT 102 deccolm escape sequencethat switches 

between 80 and 132 column modeisignored. Thisoption 
causes the deccolm escape sequenceto be recognized, and the 
xterm window will resi ze ap prop ri atei y. 

-ah Thisoption indicatesthat xterm should always highlight the 

textcursor. By default, xterm will display a hollowtextcursor 
whenever the focus is lost or the poi nter leaves the wi ndow. 

ah Thisoption indicatesthat xterm should do text cursor 

highlighting based on focus. 

-b n u mbe r T his option specifies the size of the inner border (the distance 

between the outer edge of the characters and the wi ndow 
border) in pixel s. Thedefault is 2. 

-cb Set the VtlOO resource cutToBeginningOf Line to False, 

cb Set the VtlOO resource cutToBeginningOf Line tO True. 

-ce characterci a s s r a n g e : T his sets classes i ndicated by thegiven rangesto usein 

vai uè [, . . .] selecting by words. Seethesubsection "Character Classes." 

-cn Thisoption indicatesthat newlines should notbecutin line- 

mode sei ections. 

cn Thisoption indicatesthat newlines should becut in line-mode 

sei ections 

-cr color This option specifies the color to usefor text cursor. The 

default isto usethesameforeground color that isused for text. 

-cu Thisoption indicatesthat xterm should work around a bug in 

themore(l) program that causes itto incorrectly display lines 
that are exactly the width of thewindow and arefollowed by a 
line begi nni ng with a tab (the leadi ng tabs are not displayed). 
Thisoption isso named because it was ori ginally thoughtto 
bea bug in thecurses(3x) cursor motion package 

cu Thisoption indicatesthat xterm should not work around the 

more(3x) bug mentioned in the precedi ng paragraph. 

-e program T his option specifies the program (and its command-line 

[ arguments . . . ] arguments) to be run i n the xterm window. It also sets the 

window title and icon nameto bethebasenameof the 
program bei ng executed if neither -t nor-n aregiven on 
thecommand line. This must be the last option on the 
command line. 

-tb font Thisoption speci fi es a font to beused when displaying bold 

text. This font must bethesameheightand width asthe 
normal font. If only oneof thenormal or bold fontsis 
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specifi ed, it will beused asthenormal font and thebold font 
will beproduced by overstriki ng this font. The default isto do 
overstriking of the normal font. 

-im Turn on theuseinsertMode resource. 

+im Turn off theuseinsertniode resource. 

-j This option indicates that xterm should do jump scrolling. 

N ormally, text is scrolled onelineat a ti me this option allows 
xterm to move multiple lines at a time so that it doesn't fall as 
far behind. Its use is strongly recommended because it makes 
xterm much faster when scanning through largeamountsof 
text. TheVTlOO escape sequencesfor enabli ng and disabling 
smooth serali aswell astheVT Optionsmenu can beused to 
turn thisfeatureon or off. 

j This option indicates that xterm should not do jump scrolling. 

-is Thisoption indicates that the shell that isstarted in thexterm 

window will bea login shell (that is, the first character of 
argv[0] will bea dash, indicatingto the shell that it should 
read theuser's .login or .prof ne). 

is Thisoption indicates that the shell that isstarted should not 

bea login shell (that is, it will bea normal subshell). 

-mb Thisoption indicates that xterm should ringamargin beli 

when theuser types near the right end of a line Thisoption 
can beturned on and off from theVT Optionsmenu. 

mb Thisoption indicates that margin beli should notberung. 

-memi 1 1 i seconds Thisoption specifies the maxi mum ti me between multiclick 

selections 

-ms color T his option specifies the color to be used for the poi nter 

cursor. The default isto usetheforeground color. 

-nb number T his option specifies the number of characters from the right 

end of aline atwhich themargin beli, if enabled, will ring. 
Thedefault is 10. 

-rw Thisoption indicates that reverse-wraparound should be 

allowed. This allows the cursor to back up from the leftmost 
column of one line to the rightmost column of theprevious 
line This is very useful for editing long shell command lines 
and isencouraged. Thisoption can beturned on and off from 
theVT 0 ptionsmenu. 

rw Thisoption indicates that reverse-wraparound should notbe 

allowed. 

-aw Thisoption indicates that auto-wraparound should be 

allowed. This allows the cursor to automati cai lywrap to the 
beginning of the next linewhen it isat the rightmost position 
of a lineand text isoutput. 

aw Thisoption indicates that auto-wraparound should notbe 

allowed. 

-s Thisoption indicatesthat xterm may serali asynchronously, 

meaning that the screen does not haveto be kept completely 
up to date whi le scrolling. This allows xterm to run faster when 
network latenciesarevery high and is typical ly useful when 
running across a very large I nternet or many gateways. 
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s Thisoption indicatesthat xterm should serali synchronously. 

-sb Thisoption indicatesthat some numberof lines that are 

scroi led off the top of thewindow should besaved and that a 

scrollbar should bedisplayed so that those lines can beviewed. 

Thisoption may beturned on and off from theVT Options 

menu. 

sb Thisoption indicatesthat a scrollbar should not bedisplayed. 

-sf Thisoption indicatesthat Sun Function Key escape codes 

should be generateci for function keys. 
sf Thisoption indicates that the standard escape codes should be 

generateci for function keys. 

-si Thisoption indicatesthat output to awindow should not 

automatically reposition thescreen to the bottom of the 
scrolling region. Thisoption can beturned on and off from 
theVT 0 ptionsmenu. 

si Thisoption indicatesthat output to awindow should cause it 

to serali to the bottom. 

-sk Thisoption indicates that pressi ng a key while usi ng the 

scrollbar to review previous lines oftext should cause the 
window to be repositioned automatically in the normal 
position at the bottom of the serali region. 

sk Thisoption indicates that pressi ng a key while using the 

scrollbar should not cause the wi ndow to be repositioned. 

-si number This option specifies the number of li nes to save that have 

been scroi led off thetop of thescreen. The default is 64. 

-t Thisoption indicatesthat xterm should start in Tektronix 

mode, ratherthan in VT102 mode. Switching between the 
two wi ndowsisdone using the 0 ptionsmenus. 

t Thisoption indicatesthat xterm should start in VT102 mode. 

-tm stri n g This option specifies a series of terminal setting keywords 

followed by the characters that should be bound to those 
functions, similar to thestty program. Allowable keywords 

include intr, quit, erase, kill, eof, eoi, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and lnext. Control 

characters may be specified as -char (for example, -c or -u) and 
-? may beused to indicate delete. 

-tn nane T his option specifies the name of the terminal type to be set in 

the term envi ronment vari able. This terminal type must exist 
in thetermcap(5) database and should haven# and co# entries. 

-ut Thisoption indicatesthat xterm shouldn't write a record into 

the system log file /etc/utmp. 

ut Thisoption indicatesthat xterm should write a record into the 

system log file /etc/utmp. 

-vb Thisoption indicates that a visual beli ispreferred overan 

audibleone. Instead of ringing the terminal beli whenever a 
C trl+G isreceived, thewindow will beflashed. 

vb Thisoption indicatesthat a visual beli should not beused. 

-wf Thisoption indicatesthat xterm should wait for thewindow to 

bemapped the first time before starti ng thesubprocess so that 
theinitial terminal size settings and envi ronment vari ables are 
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correct. It is the appi ication's responsi bility to catch subse- 
quent terminal sizechanges. 

wf Thisoption indicates that xterm show not wait before starti ng 

thesubprocess. 

-c Thisoption indicates that this window should reca ve console 

output. This is not supported on ali systems. To obtain 
consoleoutput, you must betheowner of the console device, 
and you must haveread and wri te perni ission for it. If you are 
runningx under xdm on the console screen, you may need to 
h ave the sessi on startup and reset programsexplicitly change 
the ownership of the console device in order to get this option 
to work. 

-sccn Thisoption speci fies the lasttwo lettere of thenameof a 

pseudo-terminal to usein slave mode, plus the number of the 
inherited file descri ptor. T he option isparsed "%c%c%d". This 
allows xterm to beused asan input and output channel for an 
existing program and issometimesused in speci al ized 
applications. 

Thefollowing command-lineargumentsareprovided for compati bi li ty with older versi ons. They may not be supported in 
thenext releaseastheX Toolkit provides standard opti ons that accomplish the same task. 

%geom Thisoption specifies the preferred sizeand position of the 

Tektronix window. It isshorthand for specifyi ng the 

"tekGeometry reSOUrce. 

geom Thisoption specifies the preferred position of theicon 

window. It isshorthand for specifyi ng the *iconGeometry 
resource. 

-t st ri ng Thisoption specifies the title for xterm's wi ndows. It is 

equivalent to -titie. 

-n stri n g T his option specifies the icon name for xterm's Windows. 1 1 is 

shorthand for speci fying the nconName resource. N ote that this 
isnot the same as the toolkit option -name (seebelow).The 
default icon nameistheapplication name. 

-r Thisoption indicates that reverse video should besimulated by 

swappingtheforeground and background colors. It is 
equivalent to -rv. 

-w number T his option specifies the width in pixels of the border 

surroundingthe window. It is equivalent to -borderwidth or 

-bw. 

Thefollowing standard X Toolkit command-lineargumentsarecommonly used with xterm: 

-bg color T his option specifies the color to usefor the background of the 

window. The default iswhite. 

-bd color Thisoption specifies the color to usefor theborder of the 

window. The default isbiack. 
-bw number Thisoption specifies the width in pixels of theborder 

surroundingthe window. 

-tg color Thisoption specifiesthecolorto usefor displayingtext. The 

default isbiack. 

-tn font Thisoption specifies the font to beused for displaying normal 

text. The default isfixed. 
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-title s t r i ng 



-geometry geomet r y 

-display di spi ay 
-xrm resourcestri ng 



RESOURCES 

The program understands ali of the 

iconGeometry (class IconGeometry) 

iconName (class IconName) 
termName (class TermName) 

title (class Title) 

ttyModes (class TtyModes) 



uselnsertMode 

(class UselnsertMode) 

utmplnhibit (class Utmplnhibit) 

sunFunctionKeys 

(class SunFunctionKeys) 

waitForMap (class WaitForMap) 



Thisoption specifiesthe application name under whi eh 
resources areto beobtained, ratherthan the default executable 
filename. Nameshould notcontain . or* characters. 
Thisoption specifiesthewindow title stri ng, which may be 
displayed by window managers if the user so chooses. The 
default title is the command linespecified after the -e option, 
if any; otherwise, the application name. 
Thisoption indicates that reverse video should besimulated by 
swappingtheforeground and background colors. 
Thisoption specifies the preferred sizeand position of the 
VT102 window; seex(l). 

Thisoption specifies theX server to contact; seex(l). 
Thisoption specifies a resource stri ngto beused. Thisis 
especially useful for setting resources that do not have separate 
command-lineoptions. 

Thisoption indicates that xterm should ask thewindow 
manager to start it asan icon ratherthan asthenormal 
window. 



coreX Tool kit resource names and classesaswell asthefollowing: 

Specifies the preferred sizeand position of the application 
when iconified. Itis not necessari lyobeyed by ali window 
managers. 

Specifies the icon name The default is the application name. 
Specifies the terminal typenameto be set in the term 
environment variable. 

Specifies a stri ng that may beused by thewindow manager 
when displayingthisapplication. 

Specifies a stri ng containing terminal setting keywords and the 
characters to which they may be bound. Allowable keywords 

include intr, quit, erase, kill, eof, eoi, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and lnext. Control 

characters may be specified as •cnar (for example, "c or "u) and 
"? may beused to indicate delete. This isvery useful for 
overriding the default terminal setti ngswithout havingto do 
an stty every timean xterm isstarted. 
Force useof insert modeby adding appropriate entriesto the 
termcap environment variable. Thisis useful if the system 

termeap isbroken. Thedefault ÌS False. 

Specifies whether or not xterm should tryto record the user's 
terminal in /etc/utmp. 

Specifies whether or not Sun Function Key escape codes 
should begenerated for function keys instead of standard 
escape sequences. 

Specifies whether or not xterm should wait for the initial 
window map before starti ng the subprocess. Thedefault is 

false. 
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T he followi ng resources are specified as part of thevtlOO widget ( class vtibb): 

Specifieswhetheror not synthetic keyand button 
events (generated usi ng the x protocol sendEvent request) 
should beinterpreted or discarded. The default is False, 



allowSendEvents 

(class AllowSendEvents) 



alwaysHighlight 

(class AlwaysHighlight) 



appcursorDef ault 

(class AppcursorDef ault) 

appkeypadDef ault 

(class AppkeypadDef ault) 

autoWrap (class AutoWrap) 

bellSuppressTime 

(class BellSuppressTime) 



boldFont (class BoldFont) 

c132 (class C132) 

cutNewline 

(class CutNewline) 

cutToBeginningOf Line 

(class CutToBeginningOf Line) 

charClass (class CharClass) 



curses (class Curses) 



background 

(class Background) 

foreground 

(class Foreground) 



cursorColor 

(class Foreground) 

eightBitlnput 

(class EightBitlnput) 



meaningthey arediscarded. N otethat allowing such events 

creates a very I arge secu ri ty h 0 1 e. 

Specifieswhetheror not xterm should always display 

a highlighted text cursor. By default, a hollow text cursor is 

displayed whenever the pointer movesout of thewindow or 

thewindow losestheinput focus. 

If true, the cursor keys are initially in application mode. 

The default istaise. 

If true, the keypad keys are initially in application mode 
The default istaise. 

Specifieswhetheror not auto-wraparound should beenabled. 
Thedefault istrue. 

N umber of milliseconds after a beli command issent during 
which additional bellswill besuppressed. Default is 200. If set 
non-zero, additional bellswill also besuppressed until the 
server reports that processi ngof the first beli hasbeen com- 
pleted; thisfeature ismost useful with the visible beli . 
Specifiesthenameof thebold fontto useinstead of 
overstriking. 

Specifieswhether or nottheVT102 deccolm escape sequence 

should behonored. Thedefault istaise. 

If false, triple-eli cki ng to select a linedoesnot 

include theNewiine attheend oftheline. If true, the Newiine 

is selected. T he default is true. 

If false, triple-eli cki ng to select a line selects only from 

thecurrent word forward. If true, the entire line is selected. 

Thedefault istrue. 

Specifies comma-separated lists of character class bindings of 
theform [ iow-i high : vaiue. These are used in determining 
which setsof characters should betreated thesamewhen 
doing cut and paste. Seethesection on specifying character 
classes. 

Specifieswhether or not the last column buginmore(l) should 
beworked around. Seethe-cu option for detai Is. The default 

ÌSfalse. 

Specifies the color to use for the background of thewindow. 
Thedefault iswhite. 

Specifies the color to usefor displaying text in thewindow. 
Setti ng the class nameinstead of theinstancenameisan easy 
wayto haveeverythingthatwould normally appear in the text 
color change color. Thedefault isbiack. 
Specifies the color to use for the text cursor. The 
default isbiack. 

If true, metacharacters input from the keyboard are presented 
as a single character with theeighth bitturned on. If false, 
metacharacters are converted into a two-character sequence 
with the character itself preceded by ESC. Thedefault istrue. 
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eightBitOutput 

(class EightBitOutput) 

font (class Font) 
fonti (class Fonti) 
font2 (class Font2) 
font3 (class Font3) 
font4 (class Font4) 
font5 (class Font5) 
font6 (class Font6) 
geometry (class Geometry) 

hpLowerleftBugCompat 

(class HpLowerleftBugCompat) 



internalBorder 

(class BorderWidth) 

jumpScroll 

(class JumpScroll) 

loginShell 

(class LoginShell) 

marginBell 

(class MarginBell) 

multiClickTime 

(class MultiClickTime) 

multiScroll 

(class MultiScroll) 

nMarginBell (class Column) 

pointerColor 

(class Foreground) 

pointerColorBackg round 

(class Background) 

pointerShape 

(class Cursor) 

resizeGravity 

(class ResizeGravity) 



reverseVideo 

(class ReverseVideo) 



Specifies whether or not eight-bit characterssentfrom the 
host should beaccepted asis or strippai when printed. The 
default istrue. 

Specifies the nameof the normal font. The default isfixed. 
Specifi es the name of the first alternative font. 
Specifies the name of the second alternative font. 
Specifi es the nameof the third alternative font. 
Specifi es the name of the fourth alternative font. 
Specifi es the name of the f ifth alternative font. 
Specifies the nameof thesixth alternati ve font. 
Specifies the preferred sizeand positi on of theVT102 
window. 

Specifies whether to work around a bug in H P'sxdp, which 
ignorestermcap and alwayssendsESC F to movete thelower- 
left corner, true causes xterm to interpret ESC F asa request 
to movete the lower-left corner of the screen. The default is 
false. 

Specifies the number of pixels between thecharactersand the 
window border. Thedefault i s 2. 
Specifies whether or not jump serali should beused.The 
default istrue. 

Specifies whether or nottheshell to be run in thewindow 
should bestarted asa login shell. Thedefault istaise. 
Specifies whether or not the bel I should berun when theuser 
typesnear theright margin. Thedefault is false. 
Specifies the maximum time in milliseconds between 
multiclick select events. Thedefault ÌS250 milliseconds. 
Specifies whether or not serali i ng should bedoneasynchro- 
nously. Thedefault istaise. 

Specifies the number of charactersfrom theright margin at 
which the margin beli should be rung, when enabled. 
Specifies the foreground color of the pointer. Thedefault is 

XtDef aultForeground. 

Specifies the background color of the pointer. Thedefault is 

XtDef aultBackground. 

Specifies the name of the shape of the pointer. T he default is 

xterm. 

Affects the behavior when thewindow i s resi zed to be taller or 
shorter. Northwest specifi esthat the top lineof text on the 
screen stayfixed. If thewindow ismade shorter, linesare 
dropped from thebottom; if thewindow ismade taller, blank 
linesareadded at thebottom. Thisis compati blewith the 
behavior in R4. Southwest (thedefault) specifies that the 
bottom lineof text on thescreen stayfixed. If thewindow is 
made taller, additional saved lineswill bescrolled down onte 
thescreen; if thewindow ismade shorter, lineswill bescrolled 
off the top of thescreen, and the top saved lineswill be 
dropped. 

Specifies whether reverse video should besimulated. The 
default istaise. 
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reverseWrap 

(class ReverseWrap) 

saveLines 

(class SaveLines) 

scrollBar 

(class ScrollBar) 

scrollTtyOutput 
(class ScrollCond) 

scrollKey 

(class ScrollCond) 

scrollLines 

(class ScrollLines) 

signallnhibit 

(class Signallnhibit) 

tekGeometry 

(class Geometry) 

teklnhibit 

(class Teklnhibit) 

tekSmall (class TekSmall) 



tekStartup 

(class TekStartup) 

titelnhibit 

(class Titelnhibit) 



translations 

(class Translations) 

visualBell 

(class VisualBell) 

T hefollowing resources are specified as part of the tek40H 

width (class Width) 
height (class Height) 
fontLarge (class Font) 
font2 (class Font) 
font3 (class Font) 
fontSmall (class Font) 
initialFont (class InitialFont) 



Specifies whether or not reverse-wraparound should be 
enabled. The default is false. 

Specifies the number of linesto save beyond the top of the 
screen when a scrollbar isturned on. The default is 64. 
Specifies whether or not the scrollbar should bedisplayed. 
The default istaise. 

Specifies whether or not output to theterminal should 
automati cai ly cause the scrollbar to go to the bottom of the 
scrolling region. The default istrue. 
Specifies whether or not pressing a key should automati cally 
cause the scrollbar to go to the bottom of the scrolling region. 
The default isfaise. 

Specifies the number of linesthat the scroii -back and scroii- 
forw actions should use as a default. The default value is 1. 
Specifies whether or not the entri es in the M ai n Options menu 
for sending signals to xterm should bedisallowed. The default 

iSfalse. 

Specifies the preferred sizeand positi on of theTektronix 
window. 

Specifies whether or not the escape sequenceto enter 
Tektronix mode should beignored. T he default isfaise. 
Specifies whether or not theTektronix mode window should 
start in its smallest sizeif no expl i ci t geometry isgiven. Thisis 
useful when runningxterm on displayswith small screens. The 
default istaise. 

Specifies whether or not xterm should start up in Tektronix 
mode. The default istaise. 

Specifies whether or not xterm should remove ti and te 
termcap entries(used to switch between alternate screens on 
startup of many screen-oriented programs) from the termcap 
string. If set, xterm also ignores the escape sequenceto switch 
to the alternate screen. 

Specifies the key and button bindingsfor menus, selections, 

"programmed strings," and SO On. See the "ACT 1 0 N S" 

subsection, later in this section. 

Specifies whether or not a visi bl e beli (that is, flashing) should 
beused instead of an audi ble beli when Control-G is received. 
The default istaise. 

idget (class Tek40u): 
Specifies the width of theTektronix window in pixels. 
Specifies the height of theTektronixwindow in pixels. 
Specifies the large font to usein theTektronixwindow. 
Specifies font number 2 to usein theTektronixwindow. 
Specifies font number 3 to usein theTektronixwindow. 
Specifies the small font to usein theTektronixwindow. 
Specifies which of the four Tektronix fonts to use initially. 
V alues are the same as for the set - tek - text action. T he default 

isiarge. 
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ginTerminator 

(class GinTerminator) 



Theresources that may be speci fi ed for the vari ous 
widget. Thenameand classesof theentriesin each 

ThemainMenu has the followi ng entries: 

securekbd (class SmeBSB) 
allowsends (class SmeBSB) 
redraw (class SmeBSB) 
linei (class SmeLine) 
suspend (class SmeBSB) 

continue (class SmeBSB) 

interrupt (class SmeBSB) 
hangup (class SmeBSB) 
terminate (class SmeBSB) 
kill (class SmeBSB) 
line2 (class SmeLine) 
quit (class SmeBSB) 

ThevtMenu has the followi ng entries: 

scrollbar (class SmeBSB) 
jumpscroll (class SmeBSB) 
reversevideo (class SmeBSB) 
autowrap (class SmeBSB) 
reversewrap (class SmeBSB) 
autolinefeed (class SmeBSB) 
appcursor (class SmeBSB) 
appkeypad (class SmeBSB) 
scrollkey (class SmeBSB) 
scrollttyoutput 
(class SmeBSB) 
allow132 (class SmeBSB) 
cursesemul (class SmeBSB) 
visualbell (class SmeBSB) 
marginbell (class SmeBSB) 
altscreen (class SmeBSB) 
linei (class SmeLine) 
softreset (class SmeBSB) 
hardreset (class SmeBSB) 
clearsavedlines (class SmeBSB)" 
line2 (class SmeLine) 
tekshow (class SmeBSB) 
tekmode (class SmeBSB) 



Specifies what character(s) should follow a GIN 
report or status report. The possi bi liti es are none, which sends 
no terminating characters, CRoniy, which sends cr, and cr&eot, 
which sends both cr and eot. The default isnone. 

menusaredescribed in the documentati on fortheAthenasimpieMenu 
of themenusarelisted next. 



T his entry invokesthesecureo action. 

T his entry invokestheaiiow-send-events(toggie) action. 

Thisentry invokestheredrawo action. 

This is a separator. 

Thisentry invokesthesend-signai(tstp) action on systems 
that support job control. 

Thisentry invokesthesend-signai(cont) action on systems 

that support job control. 

Thisentry invokesthesend-signai(int) action. 

Thisentry invokesthesend-signai(hup) action. 

Thisentry invokesthesend-signai(term) action. 

Thisentry invokesthesend-signai(kiii) action. 

This is a separator. 

Thisentry invokes the quit o action. 



Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
action. 

Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
Thisentry iscurrently 
This is a separator. 
Thisentry invokes the 
Thisentry invokes the 
Thisentry invokes the 
This is a separator. 
Thisentry invokes the 
Thisentry invokes the 



set-scrollbar(toggle) action. 
set-jumpscroll(toggle) action, 
set ■ reverse -video (toggle) action. 
set-autowrap(toggle) action. 
set-reversewrap(toggle) action, 
set-autolinef eed(toggle) action. 
set-appcursor(toggle) action. 
set-appkeypad(toggle) action, 
set -scroll-on-key( toggle) action, 
set -scroll-on-tty -output (toggle) 

set-allow132(toggle) action. 
set-cursesemul(toggle) action. 
set-visualbell(toggle) action. 
set-marginbell(toggle) action. 

disabled. 

soft-reset() action, 
bard- reset() action. 
clear-saved-lines() action. 

set -visibilityftek, toggle) action. 
set-terminal-type(tek) action. 
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vthide (class SmeBSB) 

ThetontMenu has the followi ng entries: 

fontdefault (class SmeBSB) 
fonti (class SmeBSB) 
font2 (class SmeBSB) 
font3 (class SmeBSB) 
font4 (class SmeBSB) 
font5 (class SmeBSB) 
font6 (class SmeBSB) 
fontescape (class SmeBSB) 
fontsel (class SmeBSB) 

ThetekMenu has the following entri es: 

tektextlarge (class SmeBSB) 
tektext2 (class SmeBSB) 
tektext3 (class SmeBSB) 
tektextsmall (class SmeBSB) 
linei (class SmeLine) 
tekpage (class SmeBSB) 
tekreset (class SmeBSB) 
tekcopy (class SmeBSB) 
line2 (class SmeLine) 
vtshow (class SmeBSB) 
vtmode (class SmeBSB) 
tekhide (class SmeBSB) 

The following resourcesareuseful when 

thickness (class Thickness) 
background (class Background) 
foreground (class Foreground) 



T his entry invokestheset-visibiiity(vt,off ) action. 



Thisentry 
T his entry 
Thisentry 
Thisentry 
Thisentry 
Thisentry 
Thisentry 
Thisentry 
Thisentry 



invokestheset 
invokestheset 
invokestheset 
invokes the set 
invokestheset 
invokestheset 
invokestheset 
invokestheset 
invokestheset 



-vt-font(d) action. 
-vt-font(i ) action. 
■vt-font(2) action. 
-vt-font(3) action. 
-vt-font(4) action. 
-vt-font(5) action. 
-vt-tont(6) action. 
-vt-font(e) action. 
-vt-tont(s) action. 



Thisentry invokes theset-tek-text(i) action. 
Thisentry invokes theset-tek-text(2) action. 
Thisentry invokes theset-tek-text(3) action. 
Thisentry invokes theset-tek-text(s) action. 
Thisisaseparator. 

Thisentry invokes thetek-pageo action. 
Thisentry invokes the tek- reset o action. 
Thisentry invokes thetek-copyo action. 
Thisisaseparator. 

Thisentry invokes theset-visit>iiity(vt,toggie) action. 
Thisentry invokes theset-terminai-type(vt) action. 
Thisentry invokes theset-visit>mty(tek,toggie) action. 

speci fi ed for the Athena Scrollbar widget: 

Specifies the width in pixelsof the scrollbar. 
Specifies the color to use for the background of the scrollbar. 
Specifies the color to use for the foreground of the scrollbar. 
The"thumb" of the scrollbar isasimplecheckerboard pattern 
alternati ng pixels for foreground and background color. 



POINTER USAG E 

Once the VT 102 window iscreated, xte™ allowsyou to select text and copy itwithin the same or other Windows. 

Theselection functionsareinvoked when the pointer buttonsareused with no modifiers, and when they areused with the 
Shift key. The assignment of thefunctions described in this subsection to keys and buttons may be changed through the 
resource database; seethe"Actions" subsection later in this section. 

Pointer button one(usually left) isused to savetext into the cut buffer. M ovethecursorto the beginningof the text, and 
then hold the button down whilemovingthecursorto the end of theregion and releasi ng the button. The selected text is 
highlighted and issaved in theglobal cut buffer and madethepRiMARY selection when the button isreleased. Double-clicking 
selects by words. Triple-eli cki ng selects by lines. Quadruple-clicking goes back to characters, and so on. M ulti pie-click is 
determi ned by thetimefrom button up to button down, so you can change the selection unit in the middle of a selection. If 
the key/button bindingsspecify that an X selection isto bemade, xterm will leave the selected text highlighted for aslong as 
it isthe selection owner. 
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Pointer button two (usually middle) "types" (pastes) thetextfrom the primary selection, if any, otherwisefrom thecut 
buffer, inserti ng it askeyboard input. 

Pointer button three (usually right) extendsthecurrent selection. (Without loss of generality, you can swap "right" and "left" 
everywhere in the rest of this paragraph.) I f pressed whi le closer to the right edge of the selection than the left, it extends/ 
contracts the right edge of the selection. If you contract the selection past the left edge of the selection, xterm assumesyou 
reallymeant the left edge, restorestheoriginal selection, then extends/contracts the left edge ofthe selection. Extension starts 
in theselection unit mode that the last selection or extension wasperformed in; you can multi ple-cli ck to cycletti rough 
them. 

By cutting and pasti ng pieces of text without traili ng new lines, you can taketextfrom several placesin different Windows 
and form acommand totheshell, forexample, or take output from a program and insert it into your favorite editor. Since 
thecut buffer isglobally shared among different applicati ons, you should regard it asafilewhosecontentsyou know. The 
terminal emulator and other text programs should betreating it asif it wereatext file; that is, the text isdelimited by new 
lines. 

The serali region displays the positi on and amount of text currently showing in thewindow (highlighted) relative to the 
amount of text actually saved. As more text issaved (up to the maximum), the size ofthe highlighted area decreases. 

Clicking button onewith the pointer in the serali region movestheadjacent lineto the top ofthe di splay window. 

Clicking button three moves the top lineof the display window down to the pointer position. 

Clicking button two moves the display to a position in the saved text that correspondsto thepointer's position in the 
serali bar. 

UnliketheVT102 window, theTektronix window does notallow the copyingof text. It does allow Tektronix GIN mode, 
and in this mode the cursorwi II changefrom an arrow to a cross. Pressing any key will send that key and thecurrent 
coordi nate ofthe cross cursor. Pressing button one, two, or three will return thelettersi, m, and r, respectively. If theShift 
key is pressed when a pointer button is pressed, thecorrespondinguppercaseletter issent. To disti nguish a pointer button 
from a key, the high bitof the character is set (but this is bit isnormally stri pped unless the terminal modeisRAW; see 
tty(4) fordetails). 

MENUS 

xterm hasfour menus: mainMenu, vtMenu, fontinenu, and tekMenu. Each menu popsup under thecorrect combinationsof key 
and button presses. M ost menus are di vided into two sections, separated by a horizontal line Thetop portion contains 
various modes that can be altered. A check mark appears next to a mode that is currently acti ve. Sei ecting one of these modes 
toggles its state. The bottom portion ofthe menu consistsof command entries; selecting oneof these performs the indicateci 
function. 

The xterm menu popsup when the Control key and pointer button one are pressed in a window. The mainMenu contains 
itemsthat apply to both the VT 102 and T ektronix Windows. The SecureKeyboard modeisused when typing in passwords 
or other sensitive data in an unsecured environment. (See the "SEC U R IT Y" subsection.) Notabl e entries in the command 
section ofthe menu are the Continue, Suspend, Interrupt, H angup, Terminate and Kill, which send thesiGcoNT, sigtstp, 
sigint, sighup, sigterm, and siGKiLL signals, respectively, to the process group of theprocess running under xterm (usually 
the shell). The Continue function i s especi al ly useful if the user has accidentally typed CTRL-Z, suspending theprocess. 

The vtMenu sets various modes in the VT 102 emulation, and is popped up when the Control key and pointer button two are 
pressed in the VT 102 window. In the command section of this menu, the Soft Reset entry will reset serali regions. This can 
beconvenientwhen some program has left the serali regions set incorrectly (often a problem when usingVM S orTO PS-20). 
The Full Reset entry will clear thescreen, reset tabsto every eight columns, and reset the terminal modes (such aswrap and 
smooth serali) to their initial states just after xterm hasfinished processing the command-l ine opti ons. 

ThetontMenu sets the font used in the VT 102 window. In addi ti on to the default font and a number of alternati ves that are 
set with resources, the menu offers the font last specified by the Set Font escape sequence (see the document "Xterm Control 
Sequences") and thecurrent selection asafont name(if the primary selection isowned). 
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ThetekMenu sets various modes in theTektronixemulation, and ispopped up when the Control key and pointer button two 
arepressed in theTektronixwindow. Thecurrentfontsizeischecked in theM odessection of themenu. ThePAGE entry in 
theCommand section clears theTektronixwindow. 

SECURITY 

X environmentsdiffer in their security consciousness. M ost servers, run under xdm, arecapableof using a "magic cookie" 
authorization schemethat can provide a reasonable level of security for many people. Ifyour server isonly using a host-based 
mechanism to control access to the server (seexhost(l)), then if you enable access for a host and otherusersarealso 
permitted to run clientson that samehost, thereisevery possi bility that someonecan run an application that will use the 
basic services of the x protocol to snoop on your activities, potentially capturing a transcript of everythingyou typeat the 
keyboard. Thisisof particular concern when you want to typein a password or other sensitive data. The best solution to this 
problem isto use a better authorization mechanism that host-based control, but a si m pie mechanism existsfor protecting 
keyboard input in xterm. 

Thexterm menu (see"M enus," earlier in this section) contai ns a secure Keyboard entry which, when enabled, ensures that ali 
keyboard input isdirected only to xterm (using theGrabKeyboard protocol request). When an application promptsyou for a 
password (or other sensitive data), you can enable secure Keyboard using themenu, typein the data, and then disablesecure 
Keyboard using themenu again. Only oneX client at a ti me can secure the keyboard, so when you atterri ptto enable secure 
Keyboard, it mayfail. In thiscase, the beli will sound. If thesecure Keyboard succeeds, theforeground and background colors 
will beexchanged (asif you selected the Reverse Video entry in theM odes menu); they will beexchanged again when you 
exit secure mode If the colors do not switch, then you should bevery suspiciousthatyou arebeingspoofed. If the applica- 
tion you arerunningdisplaysa prompt beforeasking for the password, it i s saf est to enter secure mode before the prompt 
getsdisplayed, andto makesure that the prompt getsdisplayed correctly (in thenew colors), to minimizetheprobability of 
spoofing. You can also bring up themenu again and makesure that a check mark appears next to theentry. 

Secure Keyboard mode will bedisabled automatically ifyour xterm window becomes iconified (or otherwiseunmapped), or 
if you start up a reparenti ng window manager (that places a title bar or other decoration around thewindow) whilein Secure 
Keyboard mode. (Thisisafeatureof thex protocol that isn't easily overcome.) When thishappens, theforeground and 
background colors will beswitched back and thebell will sound in warning. 

CHARACTER CLASSES 

Clickingthemiddlemouse button twicein rapid succession will cause ali charactersof thesame class (for example, letters, 
whitespace, punctuation) to be selected. Sincedifferent people havedifferent preferencesforwhat should be selected (for 
example, should filenames be selected asa wholeor only the separate subnames?), the default mapping can beoverridden 
through theuseof thecbarciass (class cbarciass) resource. 

Thisresourceisa seriesof comma-separated range: vai ue pairs. The rangeiseither a single num ber or low-high in therange 
of 0 to 127, correspondingto the ASC II code for the character or charactersto beset. T hevalue is arbitrary, although the 
default table uses the character number of the fi rst character occurri ng i n the set. 

The default tableis 

static int charClass[128] = { 

/* NUL SOH STX ETX EOT ENQ ACK BEL */ 

32, 1 , 1 , 1 , 1 , 1 , 1 , 1 , 

/* BS HT NL VT NP CR SO SI */ 

1 , 32, 1 , 1 , 1 , 1 , 1 , 1 , 

/* DLE DC1 DC2 DC3 DC4 NAK SYN ETB */ 

1 , 1 , 1 , 1 , 1 , 1 , 1 , 1 , 

/* CAN EM SUB ESC FS GS RS US */ 

1 , 1 , 1 , 1 , 1 , 1 , 1 , 1 , 

/ *SP !"#$%&' */ 

32, 33, 34, 35, 36, 37, 38, 39, 
/*()*+,-./*/ 

48, 41 , 42, 43, 44, 45, 46, 47, 
1*9 1 2 3 4 5 6 7 */ 
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48, 48, 48, 48, 48, 48, 48, 48, 

/*8 9 :;< => ?*/ 

48, 48, 58, 59, 60, 61, 62, 63, 

/*@ABC D E F G*/ 

64, 48, 48, 48, 48, 48, 48, 48, 

/*HIJKLMNO*/ 

48, 48, 48, 48, 48, 48, 48, 48, 

l*P OR S T UVW*/ 

48, 48, 48, 48, 48, 48, 48, 48, 

/*XY Z [\]" */ 

48, 48, 48, 91 , 92, 93, 94, 48, 

/ * ' ab c d e fg */ 

96, 48, 48, 48, 48, 48, 48, 48, 

/*h ijklm no*/ 

48, 48, 48, 48, 48, 48, 48, 48, 

/*p q rs tu v w */ 

48, 48, 48, 48, 48, 48, 48, 48, 

/*x y zf jg" DEL */ 

48, 48, 48, 123, 124, 125, 126, 1}; 

Forexample, the string 33:48,37:48,45-47:48,64:48 indicate thattheexclamation mark, percent sign, dash, period, slash, 
and ampersand charactersshould betreated thesameway ascharacters and numbers. Thisisuseful for cutting and pasti ng 
electronic mailing addresses and filenames. 



It ispossibleto rebind keys(orsequencesof keys) to arbitrary stri ngs for input bychanging the translati ons for the vti 00 or 
tek40H widgets. Changing the tran slati ons for events other than key and button events is not expected, and will cause 
unpredictable behavior. Thefollowing actions are provi ded for usi ng within the vtioo or tek40i 4 translati ons resources: 



ACTIONS 



insert-selection 



popup-menu(menuname ) 



insert-seven-bit() 
insert-eigbt-bitO 



inserto 



bell( [per cent ] ) 



ignoreO 



keymap(name ) 



(sour cenarne [, ...]) 



Thisaction ringsthekeyboard beli at the speci fi ed percentage 
abo ve or bel ow th e base vo I u m e. 
Thisaction ignorestheevent but checks for special pointer 
posi ti on escape sequences. 

Thisaction insertsthecharacter or string associ ated with the 
key thatwaspressed. 
Thisaction isasynonym for inserto. 
Thisaction inserts an eight-bit (M età) version of thecharacter 
or string associated with the key that was pressed. Theexact 
action dependson thevalueof theeigbtBitmput resource. 
Thisaction inserts the stri ngfound in theselection or cut 
buffer indicated by sourcename. Sources are checked in 
theordergiven (case is significanti unti I oneisfound. 
Commonly used selections include primary, secondary, and 
clipboard. C ut buffers are typically named cut_buffer0 
through cut_buffer7. 

Thisaction dynamically definesa new translation tablewhose 
resource nameisname with the suffix Keymap {case i s signifi- 
cant). The name None resto res the ori gin al translation table. 
Thisaction di splays the specified pop-up menu. Valid names 
(case is significanti include maininenu, vtnienu, tontMenu, and 

tekMenu. 



securef ) 



Thisaction togglestheSecureKeyboard modedescribed in the 
"Security" subsection, and isinvoked from thesecurekbd entry 

in mainMenu. 
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select-start ( ) 



select-extend() 

select-end 
(destname [, ...]) 
select-cursor-start() 

select-cursor-end 
(d e s t n a me [ , . . . ] ) 
set-vt-font 

(d/l/2/3/4/5/6/e/s 

[, normal font [ , boi dfont ]]) 



start -extend() 
start-cursor-extend() 
stringfst ring) 

scroll-back(count [,units]) 

scroll-forw(count [,uni ts ]) 

allow-send-events 

(on/off/toggl e) 
redrawf ) 

send-signal(s i g n a me ) 



quit( 



This action begins text selection at thecurrent pointer 
location. Seethesubsection on "Pointer Usage" for informa- 
tion on making selections. 

This action tracks the pointer and extends the selection. It 

should only bebound to M otion events. 

This action putsthecurrently selected text into ali of the 

selections or cut buffers specified by destname. 

Thisaction issi milar to seiect-start exceptthat it begins the 

selection at the current text cursor position. 

Thisaction is si milar to seiect-end exceptthat it should 

beused with select-cursor-start. 

This action sets the f o n t o r f o n ts cu rren ti y bei n g 
used in theVT102 window. The first argument isa 
si ngle character that specifies the font to beused: d orD 
indicate the default font (the font initially used when xterm 
wasstarted), lthrough 6 indicate the fonts specified bythe 
fonti through font6 resources, e or e indicate the normal and 
bold fonts that havebeen set through escape codes (or 
specified asthesecond and third action arguments, respec- 
tively), ands ors i ndicate the font selection (asmadeby 
programssuch asxfontsei(l)) indicated by thesecond action 
argument. 

Thisaction issimilarto seiect-start exceptthat the selection 
isextended to thecurrent pointer location. 
Thisaction issimilarto seiect-extend exceptthat the selection 
is extended to the current text cursor position. 
Thisaction inserts the specified text string asif it had been 
typed. Quotation isnecessary if the string containswhitespace 
or nonalphanumeric characters. If the string argument begins 
with the characters 0x, it isinterpreted as a hex character 
Constant. 

Thisaction scrolls the text window backward so that text that 
had previously scrolled off thetopof thescreen is now visi ble. 
Thecount argument indicates thenumber of units(which 
may be page, half page, pixel, or line) by which to serali. 
Thisaction serali issimilarto scroii-back exceptthat it scrolls 
theother direction. 

Thisaction setortogglestheaiiowsendEvents resourceand is 
also invoked by theaiiowsends entry in mainMenu. 
Thisaction redraws the window and is also invoked by the 

redraw entry in mainMenu. 

Thisaction sendsthesignal named by s i gname to the xterm 
subprocess(theshell or program specified with the -e 
command-lineoption) and is also invoked by thesuspend, 

continue, interrupt, hangup, terminate, and kill entri es in 

mainMenu. Al lowablesignal names are (case isnot significanti 
tstp (if supported by the operati ng system), suspend (sameas 
tstp), cont (if supported by the operating system), int, nup, 

term, quit, ai™, alarm (same 3S alrm), and kill. 

Thisaction sendsasiGHUP to the subprogram and exits It is 
also invoked bythe quit entry in mainMenu. 



set-scrollbar(on/ of f / 1 oggi e ) 

set-jumpscroll(on/ of f / 1 oggi e ) 

set -reverse- video (on/ of f / 1 oggi e ) 

set-autowrap(on / of f / 1 oggi e ) 

set-reversewrap(on/ of f / 1 oggi e ) 

set-autolinef eed(on/ of f / 1 oggi e ) 

set-appcursor(on/ of f / 1 oggi e ) 

set-appkeypad(on/ of f / 1 oggi e ) 

set-scroll-on-key(on/ of f / 1 oggi e ) 

set -scroll-on-tty -output (on/ of f / 1 oggi e ) 

set-allow132(on/ of f / 1 oggi e ) 

set-cursesemul(on/ of f / 1 oggi e ) 

set -visual- beli (on / of f / 1 oggi e ) 

set-marginbell(on/ of f / 1 oggi e ) 

set-altscreen(on/ of f / 1 oggi e ) 
soft -reseti) 

hard-reset( ) 
clear-saved-lines() 
set -terminal -typeft ype ) 
set-visibility(vt / 1 e k , on/ of f / 1 oggi e ) 
set-tek-text(l ar ge/ 2/ 3/ s mal I ) 

tek-page( ) 



xterm 




Thisaction togglesthescroiibar resourceand isalso invoked 
by the scroiibar entry in vtinenu. 

Thisaction togglesthe jumpscroii resourceand isalso invoked 

by thejumpscroii entry in vtMenu. 

Thisaction togglesthereversevideo resourceand isalso 

invoked bythereversevideo entry in vtMenu. 

This action toggles automatic wrapping of long lines and is 

also invoked by theautowrap entry in vtMenu. 

Thisaction togglesthe reversewrap resourceand isalso 

invoked by the reversewrap entry in vtMenu. 

Thisaction toggles automatic insertion of line-feedsand isalso 

invoked by theautolinefeed entry in vtMenu. 

Thisaction toggles the handling Application Cursor Key mode 
and isalso invoked by the appcursor entry in vtMenu. 
Thisaction toggles the handling of Application Key-pad mode 
and isalso invoked by theappkeypad entry in vtMenu. 
Thisaction togglesthe scroiiKey resourceand isalso 
invoked from the scroiikey entry in vtMenu. 

Thisaction toggles the scroirrtyoutput resourceand isalso 
invoked from thescroiittyoutput entry in vtMenu. 
Thisaction toggles the ci 32 resourceand isalso invoked from 

theallow132 entry in vtMenu. 

Thisaction toggles the curses resourceand isalso invoked 

from thecursesemul entry in vtMenu. 

Thisaction toggles the visuaiBeii resourceand isalso invoked 

by thevisualbell entry in vtMenu. 

Thisaction toggles the marginBeii resourceand isalso invoked 

from themarginbell entry in vtMenu. 

Thisaction toggles between the alternate and current screens. 
Thisaction resets the scroi ling region and isalso invoked from 

the softreset entry in vtMenu. 

Thisaction resets the scroi ling region, tabs, window size, and 
cursor keys, and clearsthescreen. It isalso invoked from the 

hardreset entry in vtMenu. 

Thisaction does hard -reseti) and also clearsthehistory of 
lines saved off the top of thescreen. It isalso invoked from the 

clearsavedlines entry in vtMenu. 

Thisaction directs output to either the vt ortek Windows, 
according to thetype stri ng. It isalso invoked by thetekmode 
entry in vtMenu and thevtmode entry in tekMenu. 
Thisaction controlswhether or notthevt or tek Windows 
are visi ble. It isalso invoked from theteksnowand vthide 

entri es in vtMenu and thevtshow and tekhide entri es in tekMenu. 

Thisaction setsfontused in theTektronix window to 
thevalue Of theresourcestektextlarge, tektext2, tektext3, 
and tektextsmaii accordingto theargument. It isalso 
by the entri es of the same names as the resources i n tekMenu. 
Thisaction clears theTektronix window and isalso invoked 
by the tekpage entry i n tekMenu. 
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tek-copy() 



tek- reset () 



visual-bell() 



Thisaction resetstheTektronixwindow and isalso invoked 
by the tekreset entry in tekMenu. 
Thisaction copies the escape codesused to generate the 
currentwindow contentsto a fi le in thecurrent directory 
beginning with thenamecoPY. It isalso invoked from the 

tekcopy entry in tekMenu. 

Thisaction flashes thewindow quickly. 



TheTektronixwindow al so hasthefollowing action: 



gin-press(l / U mi HI ti R ) 



Thisaction sends theindicated graphicsinput code. 



Thedefault bindings in theVT102 window are 

Shift <KeyPress> Prior: scroll-back(1 .halfpage) \n\ 
Shift <KeyPress> Next: scroll-forw(1 ,halfpage) \n\ 
Shift <KeyPress> Select: select -cursor-start ( ) \ 
select-cursor-end(PRIMARY, CUT_BUFFER0) \n\ 

Shift <KeyPress> Inserti insert-selection(PRIMARY, CUT_BUFFER0) \n\ 

"Meta<KeyPress>: insert-seven-bit( ) \n\ 

Meta<KeyPress>: insert -eight -bit ( ) \n\ 

!Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

"Meta <Btn1Down>: select - start ( ) \n\ 

"Meta <Btn1Motion>: select-extend( ) \n\ 

!Ctrl <Btn2Down>: popup-menu(vtMenu) \n\ 

!Lock Ctrl <Btn2Down>: popup-m 

Thedefault bindings in theTektronix window are 

"Meta<KeyPress>: insert-seven-bit( ) \n\ 
Meta<KeyPress>: insert -eight -bit ( ) \n\ 
!Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 
!Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 
!Mod2 Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 
!Mod2 Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 
!Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 
ILock Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 
!Mod2 Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 
!Mod2 Lock Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 
Shift "Meta<Btn1Down>: gin-press(L) \n\ 
"Meta<Btn1Down>: gin-press(l) \n\ 
Shift "Meta<Btn2Down>: gin-press(M) \n\ 
"Meta<Btn2Down>: gin-press(m) \n\ 
Shift "Meta<Btn3Down>: gin-press(R) \n\ 
"Meta<Btn3Down>: gin-press(r) 

Below isasamplehow of thekeymapo action isused to add special keysfor enteringcommonly typed works: 

*VT100.Translations: #override <Key>F13: keymap(dbx) 

VT100.dbxKeymap.translations: \ 

<Key>F14: keymap(None) \n\ 

<Key>F17: stringi "next" ) string(0x0d) \n\ 

<Key>F18: stringi " step" ) string(0x0d) \n\ 

<Key>F19: stringi "continue" ) string(0x0d) \n\ 

<Key>F20: string("print ") insert-selection(PRIMARY, CUT_BUFFER0) 




ENVIRO NMENT 

xterm sets the environment variables term and termcap properly for thesizewindow you havecreated. It also usesand setsthe 
environment vari able display to speci fywhich bit map display terminal to use. The environment vari ablewiNDowiD isset to 
theX window id numberof the xterm window. 

SEE ALSO 

resize(l), x(l), pty(4), tty(4) 
Xterm Control Sequences 

BUGS 

Largepastesdo not work on somesystems. Thisisnot a bug in xterm; it isa bug in the pseudo-terminal driver of those 
systems. xterm feeds large pastesto thepty only as fast asthepty will accept data, but somepty driversdo not return enough 
information to know if thewrite hassucceeded. 

M any of theoptionsare not resettab le after xterm starts. 

Onlyfixed-width, character-cell fontsaresupported. 

This program stili needsto berewritten. It should be split into very modular sections, with thevariousemulators being 
completely separate widgets that don't know about each other. I deal ly, you'd liketo beableto pick and chooseemulator 
widgetsand stick them into a single control widget. 

Thereneeds to beadialog box to allow entry of theTek copy filmarne. 
AUTHORS 

Far too many people, including Loretta Guarino Reid (D EC-U EG-W SL), Joel M cCormack (D EC-U EG-W SL), Terry 
Weissman (DEC-UEG-WSL), Edward M oy (Berkeley), Ralph R. Swick(M IT-Athena), M ark Vandevoorde(M IT-Athena), 
Bob M cN amara (DEC-M AD), Jim Gettys(M IT-Athena), Bob Scheifler (M IT X Consortium), Doug M ink (SAO), Steve 
Pitschke (Stellar), Ron N ewman (M IT-Athena), Jim Fulton (M IT X Consortium), DaveSerisky (H P), Jonathan Kamens 
(M IT-Athena) 
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Xvfb 

xvtb— Virtual framebufferX server forX Version 11 
SYNOPSIS 

Xvfb [ option ] ... 

DESCRIPTION 

xvtb isan X server that can run on machineswith no display hardware and no physi cai input devices. It emulatela dumb 
framebuffer usi ng virtual memory. 

Theprimary use of this server is intended to be server testi ng. Themfb or cfb code for any depth can beexercised with this 
server without the need for real hardware that supports the desired depths. 

A secondary use istesting clients against unusual depths and screen configurations. 
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OPTIONS 

In additi on to thenormal server options described in thexserver(l) manual page, xvfb acceptsthefollowingcommand-line 
switches: 



-screen screennum Wx H x D 



-pixdepths list- o f - d e p t h s 



-fbdir framebuffer- di r ect or y 



-shmem 



Thisoption creates screen screennum and setsitswidth, height, 
and depth to w, h, and d, respectively. By default, only screen 0 
existsand has the di mensions 1280x1024x8. 
Thisoption specifiesa list of pixmap depthsthat the server 
should support in addition to thedepthsimplied by the 
supported screens. iist-of -depths isaspace-separated listof 
integersthatcan havevaluesfrom Ito 32. 
Thisoption speci fi es the directory in which thememory- 
mapped fi les contai ning the framebuffer memory should be 
created. (See "Files.") Thisoption only existson machinesthat 
havethemmap and msync system calls. 
Thisoption speci fiesthat the framebuffer should beput in 
shared memory. The shared memory ID for each screen will be 
pri nted by the server. The shared memory is i n xwd format. 
Thisoption only existson machinesthat support theSystem V 
shared memory interface. 



If neither -shmem nor -fbdir is specified, the framebuffer memory will be allocateci with maiioct 



FILES 

T hefollowing file is created if the -fbdir option isgiven: 

framebuffer- di r ect or y 
/Xvf b_screen<n> 

EXAMPLES 

Xvfb :1 -screen 0 1600x1200x32 
Xvfb :1 -screen 1 1600x1200x16 



Xvfb -pixdepths 3 27 
-fbdir /usr/tmp 



xwud -in /usr/tmp/Xvf b screenO 

SEEALSO 

x(l), Xserver(l), xwd(l), xwud(l), XWDFile.h 

AUTHORS 

David P. Wiggins(X Consortium, Inc.) 



M emory-mapped fi le contai ning screen n's framebuffer 
memory, onerile per screen. Thefileis in xwd format. 



The server will li sten for connectionsas server number 1, and 
screen 0 will be depth 32 1600x1200. 
Theserverwill li sten for connectionsas server number 1, will 
have the default screen confi guration (onescreen, 
1280x1024x8), and screen 1 will be depth 16 1600x1200. 
Theserverwill li sten for connectionsas server number 0, 
will have the default screen configuration (onescreen, 
1280x1024x8), will also support pixmap depthsof 3 and 27, 
and will use memory-mapped fi les in /usr/tmp for the 
framebuffer. 

D isplays screen 0 of the server started by the precedi ng 
example. 
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xvidtune 

xvidtune 

xvidtune— Video mode tuner for XF rea86 
SYNOPSIS 

xvidtune [ -prev j -next j -unlock j -query j -saver suspendti me [ ti f t i me ] ] [ — t oolkitoption ... ] 

DESCRIPTION 

xvidtune isaclient interface to theXFree86 X server video modeextension (XFree86-VidM odeExtension). 

When given oneof thenontoolkitoptions, xvidtune previde a command-li ne interfaceto either switch thevideo mode or 
get/set monitor powersavertime-outs. 

Without any options (or with only tool kit options) it presents the user with various buttonsand slidersthat can beused to 
interactively adjust existing video modes. Itwill also pri nt the setti ngs in a format suitable for inclusi on in an xF86Config file. 



NOTE 



Theoriginal mode setti ngs can berestored by pressing the r key, andthiscan beused to restoreastablescreen in situa- 
ti onswhere the screen becomesunreadable. 



Theavailablebuttonsare 

Left 

Right 

Up 

Down 

Adjust thevideo mode so that the display wi II bemoved in the appropriate direction: 

Wider 
Narrower 
Shorter 
Taller 

Adjust the video mode so that the display size is altered appropri atei y: 

Quit Exit the program. 

Appiy Adjust the current video modeto match theselected setti ngs. 

Auto CausetheU p/Down/Right/Left, Wider/N arrower/ Shorter/ 

Taller, Restare, and the special S3 buttonsto beapplied 
immediately. Thisbutton can betoggled. 

Test Temporarily switch to theselected settings. 

Restore Return thesettingsto their originai values. 

Fetch Q uery the server for its current setti ngs. 

show Print the currently selected settings to stdout in xF86Contig 

Modeiine format. The primary selection issimilarly set. 

Next Switch thexserver to thenext video mode. 

prev Switch thexserver to the previous video mode. 

For some S3-based cards(964 and 968) thefollowing are also available 

mvertvcLK C hange the VC LK i nvert/ non in vert state. 

Eariysc C hangethe Early SC state. Thisaffects screen wrapping. 
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BiankDeiayi, BiankDeiay2 Set the blank delay values. Thisaffectsscreen wrapping. 

Acceptable values are in the range 0-7. T he values may be 
incremented or decremented with the +and - buttons, or by 
pressing the + or- keysin thetextfield. 

For S3-864/868 based cards, mvertvcLK and BiankDeiayi may beuseful. For S3Trio32/Trio64 cards, only irwertvci_K is 
available. At the moment there areno default setti ngsavailable for these chips in the video modeextension and thusthis 
featureisdisabled in xvidtune. It can beenabled by setti ng anyof the optional S3 commands in thescreen section of 
xF86Config, for example, using 

blank delay " " 0 

0PTI0NS 

xvidtune accepts the standard X Toolkitcommand-lineoptionsaswell asthefollowing: 

-prev Switch the xserver to the previous video mode. 

-next Switch the xserver to thenext video mode. 

-uniock Normally, xvidtune will disable theswitchi ng of video modes 

via hot keyswhileit isrunning. If for some reason the program 
did not exit cleanly and they are stili disabled, the program can 
bererun with thisoption to reenable the mode switchingkey 
combinations. 

-saver s u s p e n d t i me [of f t i me ] Set the suspend and off screen saver inactivity time-outs. The 

values are in seconds. 

-query D isplay the monitor parameters and extended screen saver 

time-outs. 

SEEALSO 

XF86Config(4/5) 

AUTHORS 

Kaleb S. Keithley (X Consorti um), additionsand modificationsbyjon Tombs, David Dawes, andJoeM oss 
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xvminitoppm 

xvminitoppm— Convert an XV thumbnail pictureto PPM 
SYNOPSIS 

xvminitoppm [ x v mi ni pi c ] 

DESCRIPTION 

ReadsanXV thumbnail picture (a miniature picturegenerated by theVisualSchnauzer browser) asinput. Producesa 
portable pixmap as output. 

SEEALSO 

ppm(5), xv(l) 

AUTHOR 

Copyright (c) 1993 by Ingo Wilken 

14 Decemberl993 
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xwd— Dump an imageof anX window 
SYNOPSIS 

xwd [-debug] [-help] [-nobdrs] [-out file] [-xy] [-trame] [-add vai uè] 
[-root j - ±d i d j -name name ] [-icmap] [-screen] [-display display] 

DESCRIVO N 

xwd isan X Window System window dumping utility, xwd allowsX usersto store window images in a speci al ly formatted 
dump file This file can then beread by variousother X utilitiesfor redisplay, printing, editing, formatti ng, archivi ng, image 
processing, and so on. The target window isselected by clicking the pointer in the desi red window. Thekeyboard beli is 
rung once at the beginningof the dump and twicewhen the dump iscompleted. 



OPTIONS 

-display di spi ay 

-help 
-nobdrs 



-out file 



-xy 



-add vai ne 
-trame 



-id i d 



-icmap 



Thisargument allowsyou to specify the server to connect to; 
seex(l). 

Print outtheusage: command syntaxsummary. 
Thisargument specifiesthat the window dump should not 
i nclude the pixelsthat compose the X window border. This is 
useful in situations in which you may wish to include the 
window contentsin adocumentasan illustration. 
Thisargument allowstheuser to explicitly specify the output 
fileon the command line The default isto output to standard 
out. 

Thisoption appliesto color displaysonly. 1 1 sei ectsxY format 
dum pi ng i nstead of the default z format. 
Thisoption speci fi es a si gn ed valueto be added to every pixel. 
Thisoption indicatesthatthewindow manager f rame should 
beincluded when manually selecting a window. 
Thisoption indicatesthattherootwindow should beselected 
for the window dump, without requiring the user to select a 
window with the pointer. 

Thisoption indicatesthatthewindow with thespecified 
resourcei t should beselected forthewindow dump, without 
requiringtheuserto select awindow with thepointer. 
Thisoption indicatesthatthewindow with thespecified 
wm_name property should beselected forthewindow dump, 
without requiringtheuserto select awindow with thepointer. 
N ormally, thecolormap of thechosen window isused to 
obtain RGB values. This option forces the first installed 
colormap of the screen to beused instead. 
Thisoption indicatesthattheGetimage request used to obtain 
the image should bedoneon the root window, ratherthan 
directly on thespecified window. In thisway, you can obtain 
pieces of other wi ndows that overl ap the specif ied wi ndow, 
and moreimportantly, you can capturemenus or other 
popups that are i ndependent wi ndows but that appear over the 
speci fi ed window. 
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ENVIRONMENT 

display To get default host and display number 

FILES 

xwDFiie.h x W indow dump fi le format definition file. 

SEEALSO 

xwud(l), xpr(l), x(l) 

AUTHORS 

Tony D ella Fera (D igital E qui pment Corporation, M IT Project Athena) and William F. Wyatt (Smithsonian Astrophysical 

0 bservatory) 

X Version 11 Release 6 

xwdtopnm 

xwdtopnm— Convert an Xll or X10 window dump fileinto a portableanymap 
SYNOPSIS 

xwdtopnm [ x wd file] 

D ESC RIPTIO N 

Readsan Xll or X10 window dump fi le as input. Produces a portableanymap as output. T he typeof the output file 
dependson the input file. If it's black and white, api™ fileiswritten; if it's grayscale, apgm file, else a ppm file. The program 
tellsyou which typeit iswriting. 

Usingthis program, you can convert anything on an X workstation'sscreen into an anymap. Just display whatever you're 
interested in, do an xwd, run it through xwdtopnm, and then usepnmcut to select the part you want. 

BUGS 

1 haven'ttested thistool with very many configurations, so there are probably bugs. Pleaselet meknow if you find any. 
SEEALSO 

pnmtoxwd(l), pnm(5), xwd(l) 

AUTHOR 

C opyright (c) 1989, 1991 by J ef Poskanzer. 

11 January 1991 

xwininfo 

xwininfo—W indow informati on utility forX 
SYNOPSIS 

xwininfo [-help] [-id i d ] [-root] [-name name] [-int] [-children] [-tree] 
[-stats] [-bits] [-events] [-size] [-wm] [-shape] [-trame] [-ali] [-english] 
[-metric] [-display di spi ay ] 



xwininfo 



DESCRIVO N 

xwininfo is a uti lity for displaying information about Windows. Variousinformation isdisplayed dependi ng on which options 
areselected. If no options are chosen, -stats isassumed. 

The user has the opti on ofselecting the target window with the mouse (by ci ickingany mouse button in the desi red 
window) or by specifying its window id on thecommand li ne with the-id option. Or instead of specifying the window by 
itsid number, the-name option may beused to specify which window is desi red by name There isalso a special -root 
option to quickly obtain information on the screen's root window. 



OPTIONS 

-help 
-id i d 



-name name 



-int 



-children 



-bits 



-events 



Print outtheusage: command syntaxsummary. 

This option allowstheuserto specify a target window id on 

thecommand line rather than usi ng the mouse to select the 

target window. This isveryuseful in debugging X applications 

where the target window isnot mapped to thescreen orwhere 

the use of the mouse might be impossi ble or i nterfere with the 

application. 

Thisoption allowstheuserto specify thatthewindow name is 
the target window on thecommand line rather than using the 
mouse to select the target wi ndow. 
Thisoption specifiesthatX'srootwindow isthe target 
window. This isuseful in situati ons where the root window is 
completely obscured. 

Thisoption speci fi esthat ali X window idsshould be 
displayed asinteger vai ues. The default isto display them as 
hexadecimal vai ues. 

Thisoption causes the root, parent, and children Windows' ids 
and namesof the selected window to be displayed. 
Thisoption islike -children but displays ali children 
recursively. 

T h i s opti on causes the di spi ay of vari ous attri butes pertai n i ng 
to the location and appearanceof the selected window. 
Information displayed includes the location of thewindow, its 
width and height, itsdepth, borderwidth, class, colormap id if 
any, map state, backi ng-store hi nt, and location of the cornerà 
T h i s opti on causes the di spi ay of vari ous attri butes pertai n i ng 
to the selected window's raw bits and how the selected window 
isto bestored. D isplayed information includes the selected 
window's bit gravity, window gravity, backing-store hint, 
backing-planesvalue, backing pixel, and whether or notthe 

window haSsave-under Set. 

Thisoption causes theselected window'sevent masksto be 
displayed. Both theeventmask of events wanted bysome 
client and the event mask of events not to propagate are 
displayed. 

Thisoption causes the selected window's sizing hintsto be 
displayed. Displayed information includes thefollowing: for 
both thenormal sizehintsand thezoom sizehints, the user 
supplied location, if any; the program supplied location, if any; 
the user supplied size, if any; the program supplied size, if any; 
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-shape 
-trame 
-metric 

-english 



-ali 

-display di spi ay 



the minimum size, if any; the maximum size, if any; theresize 
increments, if any; and the minimum and maximum aspect 
ratios, if any. 

Thisoption causestheselected window'swindow manager 
hintsto bedisplayed. Information displayed may include 
whether ornot the application accepts input, whatthe 
window'sicon window # and nameis, wherethewindow's 
icon should go, and what the window's initial state should be. 
Thisoption causestheselected window'swindow and border 
shape extentsto bedisplayed. 

Thisoption causeswindow manager frames to be considered 
when manually selecting Windows. 
Thisoption causesall individuai height, width, and x and y 
positionsto bedisplayed in millimetersaswell asnumberof 
pixels, based on what the server thinks the resolution is. 
Geometry speci fi cati o n s th at are in +x+y form arenot changed. 
Thisoption causesall individuai height, width, and x and y 
positionsto bedisplayed in inches(and feet, yards, and milesif 
necessary) aswell as number of pixels. -metric and -engiish 
may both be enabled at the same ti me. 
Thisoption isaquick way to ask forali information possi ble. 
Thisoption allowsyou to specify the server to connectto; see 
x(l). 



EXAMPLE 

Thefollowing isasamplesummary taken with no options specified: 

xwininfo: Window id: 0x60000f "xterm" APsolute upper-left X: 2 
Absolute upper-left Y: 85 Relative upper-left X: 0 Relative upper-left Y: 25 
Width: 579 Height: 316 Depth: 8 Visual Class: PseudoColor Border width: 0 
Class: InputOutput Colormap: 0x27 (installed) Bit Gravity State: 
NorthWestGravity Window Gravity State: NorthWestGravity Backing Store State: 
NotUseful Save Under State: no Map State: IsViewable Override Redirect State: 
no Corners: +2+85 -699+85 -699-623 +2-623 -geometry 80x24+0+58 

ENVIRONMENT 

display To get thedefault host and display number 

SEEALSO 

X(l), xprop(l) 

BUGS 

Using -stats -bits showssomeredundant information. 

The -geometry string displayed must makeassumptionsabout the window's border width and thebehavior of the application 
and the window manager. Asaresult, the location given isnot alwayscorrect. 

AUTHOR 

M ark L i Ili bridge {M IT Project Athena) 

X Versi on 11 Release6 



xwud 




xwud 

xwud— Image di splayer forX 
SYNOPSIS 

xwud [-in file] [-noclick] [-geometry geom] [-display display] 
[-new] [-std <maptype>] [-raw] [ -vis <vis-type-or-id>] [-help] [-rv] 
[ -piane n u mbe r ] [-fg color] [-bg color] 



DESCRIPTION 

xwud isan X Window System imageundumping utility, xwud allowsX usersto display in awindow an image saved in a 
speci al lyformatted dump file, such asproduced byxwd(l). 



OPTIONS 

-bg color 

-display di spi ay 
-fg color 

-geometry geom 



-help 
-in file 



-noclick 



-piane number 



If abitmap image (or a single piane of an image) isdisplayed, 
thisoption can beused to specify the color to di splay for the 0 
bitsin theimage 

Thisoption allowsyou to specify the server to connectto; see 
x(l). 

If abitmap image (or a single piane of an image) isdisplayed, 
thisoption can beused to specify the color to display for the 1 
bitsin theimage. 

Thisoption allowsyou to specify the size and positi on of the 
window. Typically, you will only wantto specify the position, 
and I et the size default to the actual size of the image. 
Print out a short descri ption of the allowable options. 
Thisoption enables the user to explicitly specify the input file 
on thecommand line. If no input fi lei sgiven, the standard 
input isassumed. 

Thisoption forcesc reati on of a new colormapfor displaying 
theimage. If the image characteristicshappen to match those 
of thedisplay, thiscan get theimage on thescreen faster, but 
atthecost of using a new colormap (which on most displays 
will cause otherwindowsto go Technicolor). 
Clickingany button in the window will terminate the 
application, unless thisoption isspecified. Termination can 
always beachieved by typingq, q, orCtrl-tC. 
You can select a single bit planeof the image to display with 
thisoption. Planesarenumbered with zero being the least 
significai bit. Thisoption can beused to figure out which 
pianeta passto xpr(l) for printing. 
Thisoption forces the image to bedisplayed with whatever 
color valueshappen to currently existon thescreen. This 
option is mostly useful when undumpingan image back onta 
thesamescreen that theimage originai ly carne from, whilethe 
originai Windows are stili on thescreen, and results in getti ng 
the i mage on the screen faster. 

If abitmap image (or a single planeof an image) isdisplayed, 
thisoption forces the foreground and background colorsto be 
swapped. Thismay beneeded when displaying a bitmap image 
that has the color sense of pixel values 0 and 1 reversed from 
whatthey areon your display. 
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Thisoption causestheimageto bedisplayed usingthe 
speci f i ed standard co I o rm ap. T h e p ro perty n am e i s obtai n ed 
by converti ng the typeto uppercase, prependi ng rgb, and 
appending map. Typical types are best, default, and gray. See 
xstd-cmap(l) for oneway of creati ng standard colormaps 
Thisoption allowsyou to specify a particular visual or visual 
class. The default isto pick the"best" one A particular class 

Can bespecified: StaticGray, GrayScale, StaticColor, 
PseudoColor, DirectColor, OrTrueColor. Or Match Can be 

speci fi ed, meani ng use the same class as the source i mage. 
Alternative! y, an exact visual id (speci fic to the server) can be 
specified, either asa hexadecimal number (prefixed with 0x) or 
asadecimal number. Finally, default can bespecified, 
meaningto use the same class asthecolormap of theroot 
window. Caseisnotsignificantin any of these stri ngs. 

ENVIRONMENT 

display To get default display 

FILES 

xwDFiie.h X W indow dump file format defi nition file 

SEEALSO 

xwd(l), xpr(l), xstdcmap(l), x(l) 

AUTHOR 

Bob Scheifler (M IT X Consortium) 

X Versi on 11 Release6 

ybmtopbm 

ybmtopbm— Convert a BennetYee"face" fileinto a portable bitmap 
SYNOPSIS 

ybmtopbm [f acef il e ] 

D ESC RIPTIO N 

Readsafileacceptableto the face and xbm programsby Bennet Yee(bsy+?cs. cmu.edu). W ri tesa portable bitmap as output. 
SEEALSO 

pbmtoybm(l), pbm(5), face(l), face(5), xbm(l) 

AUTHOR 

Copyright(c) 1991 byJamieZawinski andjef Poskanzer. 

6 M arch 1990 



-std maptype 



-vis vi s-type- or - i d 




ytalk 



ytaik— A multiuser chat program. 



SYNOPSIS 



ytalk [-x] username. . . 



DESCRIPTION 



ytalk (V3.0 Patch Level 1) isin essence a multiuser chat program. It worksalmost exactly liketheU N IX talk program and 
even communicateswith thesametalk daemon(s), butYTaik allowsfor multiple connections. 

The username field may beformatted in several different ways: 



You can specify multiple usernameson thecommand line, for example, 

ytalk george fred@hissun.edu marc@grumpy.cc 

The -x option disables the X 11 interface (described below). 

For each user on thecommand line, ytalk will attempt to connect to the talk daemon on the specified user's host and 
determine if that user has left an invitation for you to cali. If not, ytalk leavesan invitation for him and tei Is histalk daemon 
to send an announcement to hisscreen. Thereisnot yet a dedicated ytaik daemon, but therewill be. Right now, ytaik is 
ableto communicatewith both existing versi onsof UNIX talkdaemons. Forany particular host, ytalk will attempt to 
communicatewith a talk daemon the cai ler's host also supports. If thetwo hostshaveno daemon in common, then U N IX 
talk will not function at ali, but a connection ispossiblethrough (and only through) ytaik. 

After a connection has been established between two users, they can chat back and forth to their hearts' content. The 
connection isterminated when oneof them hitsControl-C orselectsQuitfrom themain menu. 

ytaik isperfectly compati blewith U N IX talk and they can even converse with each otherwithout any probi ems. H owever, 
manyof the featuresof ytaik can only operate when you areconnected to auserwho is also usi ng ytaik. For the rest of this 
document, itwill beassumed that ali connected users are usi ng ytaik unlessotherwisestated. 

If you specified morethan oneuser on theytaik command line, then ytaik will processand add each userto theconversa- 
tion asthey respond to your invitation. Aseach new user enterstheconversation, thescreen isfurther subdivided into 
smaller and smaller Windows, onefor each connected user. Right now, thenumber of connected users islimited by the 
number of lineson your terminal (orwindow), for each connected user needsat least threelines. 

ytaik does implement primitivesupport of the X 11 Windowing System. If the environmentvariable display isset, then 
ytaik attemptsto connect to thatX server. Further detailsabout the X 11 interface (and how to turn it off) aregiven later in 
this section. 

Aseach new user isadded to theconversation, ytaik will transmit informati on about that user to ali other connected ytaik 
users so that their screenswill also subdivide and incorporate the new user. If the new user isusing U N IX talk, then 
information about him will NOT betransmitted, as hisscreen would beunableto accept multiple connections. I havegiven 
brief thought to allowing at least the output of U N IX talk users to betransmitted to ali connected ytaik users, but I havenot 
written any codeto do so. N otethat even though UNIX talk cannot handle multiple connections, it isstill possi ble for ytaik 
to handle multi pie U N IX "talk" connections. For example, george (usi ng ytaik) could communicatewith fred and joe (both 
usingU N IX talk), but fred and joe would beunawareof each other. The best way to understand thelimitationsthat U N IX 
"talk" placeson ytaik isto test various connections between thetwo and seehowthingswork. 



name#tty 

name#tty@host 

name@host#tty 



name 



name@host 



Some user on your machine 

Someuseron a different machine 

Someuser on a particular terminal 

Some user on a particular tty on a different machine 

SameaSname#ttyiahost 
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ESCAPE MENU 

Whenever you areusing ytaik, you can hit the Escape key to bringup a menu that atthis moment hastheseoptions: 



a Add a user 

d Delete a user 

o Options 

s Shell 

u U ser li st 

w 0 utput user to fi le 

q Quit 



By choosing option a, you are given the opportuni tyto typethenameof any user you wish to include into the conversati on. 
Again, ytalk will accept an invitation from that user if an invitation exists, orwill leavean invitation and ring the given user. 

By choosing option d, you can selectthenameof a connection to terminate. 

By choosing option o, you can view and/or modify any of theytaik options. (See the "Options" subsection fora list ofytaik 
options.) 

By choosing option s, you can invokea shell in your ytaik window. AH other userswill seewhat happens in your shell. ytaik 
will automatically resize your window down to thesizeof the smallest window you areconnected to, in order to ensurethat 
ali usersalwaysseethesamething. 

T he u option displaysa list of connected and unconnected users, aswell astheir window sizesand whatversion of talk 
software th ey are ru n n i n g. 

By choosing option w, you can select any connected user and typethenameof a file, and ali further output from that user 
will bedumped to the specified file. The fi le, if it exists, will beoverwritten. If you choosew and the same user again, further 
output to thefilewill beterminated. 

Oh, one other thing: when user A attemptsto ytalk to user B, but user B isalready ytalking with user C, user A'sytaik 
program will realizethat user B isalready usingytaik, and will communicatewith user B'sytaik program directly in order to 
initializethe conversation. U ser B will seeanicewindowed messagesuch as 

Do you wish to talk with user A? 

and he will bepromptedforayes/noanswer. This, in my opinion, ismuch preferableto bl itti ng the announcement message 
and messi ngup user B'sscreen. 

RUNTIME OPTIONS 

When you select Options from the mai n menu, you are given the opportunity to edit theytaik options. The current options 
are 



s Tum scrolling [off/on] 

w Tum word-wrap [off/on] 

i Tum auto-import [off/on] 

v Tum auto-invite [off/on] 

r Tum auto-rering [off/on] 

a Tum asides [off/on] 



If scroiiing isturned on, then a user's window will serali when he reaches the botto m, instead of wrapping back around to 
the top. 

If word-wrap isturned on, then any word thatwould overextend theright margin will be automatically moved to thenext line 
on your screen. 




If auto-import isturned on, then ytaik will assume thatyou wish to talk to any usersthat connect to other ytaik usersthat 
areconnected to you. That last sentencedoes makesense; try again. ytaik will add theseusersto your session automatically, 
without aski ng you for verificati on. 

If auto-invite isturned on, then ytaik will automatically accept any connection requested by another user and add the user 
to your session. You will not beasked for verification. 

If auto -rering isturned on, then ytaik will automatically re-ring any user who doesnot respond to your invitati on within 30 
seconda You will not beasked for verificati on. 

If asides isturned on (it may not beavailable), then keyboard input received whilethe input focus isin aspecific user's 
window will only besentto that user. (Seethe"Xll Interface" subsection.) 

Any of theseoptionscan beset to your preferencein your .ytaikrc file, asdescribed in thenext subsection. 
YTALK STARTU P FILE 

If your home directory containsafilenamed .ytaikrc, then ytaik will read thisfile while starting up. Ali ytaik runtime 
options, aswell assomestartup options, can beset in thisfile. 

SETTING BOOLEAN OPTIONS 

Boolean options can bepreset with thefollowing syntax: 

turn opti o n [off | on] 

whereoptt on iSOneof scrolling, word-wrap, auto-import, auto-invite, auto-rering, asides, OTX. Setti ng these Opti OnSWOrkS 

just likedescribed earlier in thissection. Turningx on or off will enableor disable the X 11 Interface. For example, onecould 
enable word-wrap with the I i ne: 

turn word-wrap on 

SETTING READDRESSMODES 

Thepurposeof readdressing isto allow ytaik connectionsacross point-to-point network gatewayswhere the locai machines 
know themselves by a different address (and typically hostname) than the remote machines. The basic syntax of a readdress 
command is this 

readdress f r om- ad tir es s to- address domain 

The readdress statement simply makesa claim that themachine(s) in domai n com munì cate with themachine(s) atf rom- 
address by sending a packet to t o- a ddr es s . Becausemostusershavenouseforthiswhatsoever, HI describe it only bri efly. 

THIS IS NOT ROUTING.For example, my machineat homeisconnected via PPP to the network at my office. M y 
machine at homethinksits Ethernet address is 192.1 88.253.1 and its hostname is "taiisman.com". The network at my office 
has the address 192. 67. 141 .0. W hen l'm connected via PPP, my home machine isplaced into the office network as address 

192.67.141 .9 with hostname "talisman.austin.eds.com". 

ytaik needsto know that if it isrunningon domain 192.67.141 .0 and receivespacketsfrom 192.1 88. 253.1 that it should 
respond to 192.67.141 .9, not 192.1 88. 253.1. Right?Right. Okay, okay, okay. I put this li ne into my .ytaikrc on both ends: 

readdress talisman talisman.austin.eds.com 192.67.141.0 

On my home end, thistranslatesto 

readdress 192.188.253.1 192.67.141.9 192.67.141.0 

which tei Is my homemachineto advertise itself as 192.67.141 .9 instead of 192. 188. 253.1 when ytalkingto machines on the 
network 192.67.141 .0. 0 n the office end, the readdress command translates to 

readdress 192.67.141.9 192.67.141.9 192.67.141.0 

which the office machines basi cally ignore. 

Enough. For more information on howto use this, consultthesourcecodeorsend mealetter. :-) 



Parti: U ser Commands 
Xll INTERFACE 

If the display envi ronment variable is defined when ytaik startsup, then ytaik will attempt to communicatewith thatX 
server. A window will becreated foryou and each user you areconnected to. The Xll Interface can bedisabled either by 
specifying -xon thecommand line or by puttingthislineinto your .ytaikrc file: 

turn X off 

A window iscreated foreach individuai user in theconversation. If theinputfocusisin themain window (theonewith 
ytaik in thetitlebar) then anythingtyped will besentto ali connected users. If theinputfocusisin oneof theuser's 
Windows, then anythingtyped will besent asan asideto only that user. If the aside option isturned off, then ytaik will beep 
and not accept anythingtyped when the input focus isnot in themain window. 

ytaik consultstheXll ResourceD atabase for these user-defi nable configuration options: 

ytaik. display: X server to connectto, defaultingto the display environment variable. 

ytaik . reverse: Reverse black/white pixel s. 

ytaik.font: Fontto use, defaultingto 9x15. 

ytalk.geometry: W indOW Size, defaulting tO 80x24. 

FUTURE WORK 

Work isbeing doneon thefollowing ideas: 

■ Private conversations that do not get interrupted ortransmitted to ali ytaik connections 

■ A dedicated ytaik daemon 

FILES 

/usr /locai/ et c/ytalkrc 
SHOME/ .ytaikrc 

AUTHOR 

Britt Yen ne (yenne@austin . eds . com) 

CONTRIBUTORS 

Special thanksto Cari Edman for numerouscodepatches, beta testi ng, and comments. I think thisguy spendsas much ti me 
on ytaik asl do. Special thanksto Tobias H ahn and G eoff W . for beta testi ng and suggestions. Thanksto Sitaram 
Ramaswamy for the originai ytaik man page. Thanksto M agnusH ammerin for Solaris 2.* support. Thankstojonas 
Y ngvesson for aside messages i n X . T hanks to Andreas Stolcke for fixi ng the X resource database cai Is. T hanks to J ohn 
Vanderpool, Shih-Chen Huang, Andrew Myers, Duncan Sinclair, Evan M cLean, and Larry Schwimmer for comments and 
ideas. The readme fileshipped with ytaik givesdetailed attributions. 

BUGS 

If you haveany ideas, comments, orquestions, l'd be happy to hearfrom you atytaiwaustin.eds.com. 

24 junel993 

yuvplittoppm 

yuvpiittoppm— Converta y-, au-, and av- fileinto aportablepixmap. 
SYNOPSIS 

yuvsplittoppm b a s e n a me width height [-ccir601] 



Systemwidedefaults file. 

User's locai configuration file This file overrides options set in 
thesystem ytaikrc file. 



zcmp, zdiff 



DESCRIVO N 

Readsthree files, containing theYUV components, as input. These fi les are basename.Y, basename.u and basename.v. Produces 
a portaPle pixmap on stdout. 

Si nce theYUV filesareraw files, thedimensionswidth and height must Pespecified on thecommand line 
OPTIONS 

-ccir60i AssumesthattheYUV triplets are scaled into the smaller range 

of theCCIR 601 (M PEG) standard. Otherwise theJFIF 
(JPEG) standard isassumed. 

SEEALSO 

ppmtoyuvsplit(l), yuvtoppm(l), ppm(5) 

AUTHOR 

M arcel W ijkstra (<wijkstraefwi.uva.ni>), based on ppmtoyuvspiit 

26 August 1993 

yuvtoppm 

yuvtoppm— Convert APekasYU V Pytes into a portaPle pixmap 
SYNOPSIS 

yuvtoppm w i d t h height [imagedata] 

DESCRIPTION 

Readsraw APekasYU V Pytes asinput. Produces a portaPle pixmap as output. The input file isjustYU V Pytes. You h ave to 
speci fy the width and height on thecommand line, si nce the program oPviously can't get them from the fi le Themaxvai is 
assumed to Pe255. 

SEEALSO 

ppmtoyuv(l), ppm(5) 

AUTHOR 

M are Boucher(<marc@Postimage.coM>)), Pased on ExampleConversion Program, A60/A64 Digital Video Interface M anual, 
page 69. Copyright (c) 1991 Py D H D Postlmage, Inc. Copyright (c) 1987 PyAPekas Video Systems, Inc. 

25 M ardi 1991 

zcmp, zdiff 

zcmp, zdiff— Compare compressed files 
SYNOPSIS 

zcmp [ cmp_options ] filel [ file2 ] 
zdiff [diff_options ] filel [ file2 ] 
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D ESC RIPTIO N 

zcmp and zdiff areused to invokethecmp orthediff program on compressed files. Ali optionsspecified arepassed di rectly to 
cmp or dif f . If only one fi le is specified, then thefilescompared aremei and an uncompressed fiiei .gz. If two files are 
specified, then they are uncompressed if necessary and fed to cmp or diff. The exit status from cmp or dif f ispreserved. 

SEEALSO 

cmp(l), diff(l), zmore(l), zgrep(l), znew(l), zforce(l), gzip(l), gzexe(l) 

BUGS 

M essagesfrom the cmp or diff programsrefer to temporary fi lenames i nstead of those specified. 

zeisstopnm 

zeisstopnm— Convert aZeissconfocal fileinto a portableanymap 
SYNOPSIS 

zeisstopnm [ -pg m j -ppm] [z e i s s f i I e ] 

DESCRIPTION 

Reads a Zeiss confocal fi le as i nput. Produces a portable anymap as output. T he type of the output file depends on the input 
fi I e — i f i t's grayscal e, apgm filewill beproduced; otherwise itwill beappm file The program tellsyou which type it is 
writing. 

OPTIONS 

-pgm Force the output to be apgm file 

-ppm Force the output to beappm file 

SEEALSO 

pnm(5) 

AUTHOR 

Copyright (c) 1993 by Oliver Trep te. 

15 Junel993 

zforce 

zforce— Forcea .gz extension on ali gzip files 
SYNOPSIS 

zforce [ name ... ] 

DESCRIPTION 

zforce forcesa .gz extension on ali gzip files so that gzip wi II not compress them twice. Thiscan beuseful forfileswith 
namestruncated after a file transfer. On systemswith a 14-character limitation onfilenames, theoriginal nameistruncated 
to makeroom forthe .gz suffix. For example, 12345678901234 isrenamed to 12345578901 .gz. A filenamesuch asfoo.tgz isleft 
intact. 



zmore 



SEEALSO 

gzip(l), znew(l), zmore(l), zgrep(l), zdiff(l), gzexe(l) 



zgrep 



zgrep— Search possibly compresseci files for a regular expression 
SYNOPSIS 

zgrep [ grep_options ] [-e] pattern filename... 

D ESC RIFTIO N 

zgrep isused to invoke the grep on compresseci orgziped files. Ali optionsspecified arepassed d i recti y to grep. If no fileis 
specified, then the standard input isdecompressed if necessary and fed to grep. 0 therwise, the given files are uncompressed if 
necessary and fed to grep. 

If zgrep isinvoked aszegrep Or zfgrep, then egrep Orfgrep ÌSUSed instead Of grep. If the grep environment variable is set, 
zgrep usesit as the grep program to beinvoked. For example, 

for sh: GREP=fgrep zgrep strìng files for osti: (setenv GREP fgrep; zgrep string files) 

AUTHOR 

C harles Levert (charlesfcomm . polymtl . ca) 

SEEALSO 

grep(l), egrep(l), fgrep(l), zdiff(l), zmore(l), znew(l), zforce(l), gzip(l), gzexe(l) 

zmore 

zmore— File perusal filter for crt viewi ng of compressed text 
SYNOPSIS 

zmore [ name ... ] 

DESCRIPTION 

zmore i s a fi Iter that allowsexamination of compressed or plain textfilesonescreenful at a timeon a soft-copy terminal, zmore 
works on files compressed with compress, pack, orgzip, and also on uncompressed files. If afiledoes not exist, zmore looksfor 
afileof the same name with the addi tion of a .gz, .z, or .z suffix. 

zmore normally pauses after each screenful, printing -More- at thebottom of thescreen. If the user then types a carri age 
return, one more line isdisplayed. If the user hits a space, another screenful isdisplayed. Other possibilities are enumerateci 
later. 

zmore looksin the fi le /etc/termcap to determi ne terminal characteristics, and to determi ne the default window size. On a 
terminal capableof displaying 24 lines, the default window size is 22 lines. To use a pager other than the default more, set 
environment variable PAGERto the name of the desi red program, such asiess. 

Other sequencesthat may betyped when zmore pauses, and their effects, areasfollows (i isan optional integer argument, 
defaultingto 1) : 

<space> Display! more lines, (or another screenful if no argument is 

given). 

"d D isplay 11 more lines (a "serali"). If i is given, then the scroi I 

size is setto i. 

d Sameas "D (control-D) 
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i z Sameastypingaspaceexceptthati, if present, becomesthe 

new window size. N otethat thewindow size ra/erts back to 
the default at the end of the current file, 
s Skipi lines and print a screenful of lines. 

f Skipi screenfuls and print a screenful of lines. 

q oro Quit reading thecurrent file; go on to thenext (if any). 

eorq Whentheprompt-More-(Next file: fi i e) isprinted, this 

command causes zmore tO exit. 

s Whentheprompt-More-(Next file: fi i e) isprinted, this 

command causes zmore to skip thenext fi le and continue. 
D i splay thecurrent line number. 
/expr Search forthei th occurrenceof theregularexpression expr. If 

the pattern is not found, zmore goes on to the next file (if any). 
Otherwise, ascreenful isdisplayed, starti ng two lines before 
theplacewheretheexpression was found. The user's erase and 
kill characters may be used to edit the regular expression. 
Erasing back past the first column cancels the search 
command. 

n Search forthei th occurrenceof the last regular expression 

entered. 

icommand I nvoke a Shell with c o mma n d . T he Character ! i n c o mira n d is 

replaced with the previous shell command. The sequence\! is 
replaced by !. 

:q or :q Quit readi ng the current file; go on to thenext (if any) (same 

asq oro). 

(dot) Repeat the previous command. 

The commands take effect immediately; that is, it is not necessary to type a carri age return. Up to thetimewhen the 
command character itself isgiven, the user may hit the line kill character to canee! thenumerical argument beingformed. In 
addition, the user may hit the erase character to redisplay the -More- message. 

At any timewhen output isbeing sent to the terminal, the user can hit the quit key (normally Control- n). zmore will stop 
sending output, and will display the usuai -More- prompt. The user may then enteroneoftheprecedingcommandsinthe 
normal manner. U nfortunately, some output islostwhen thisisdonebecauseany characters wai ti ng in the termi nal's output 
queueareflushed when the quit signal occurs. 

Theterminal is set to noecho mode by this program so that the output can be conti nuous. Whatyou type will thusnotshow 
on your terminal, exceptforthe/ and ! commands. 

If the standard output isnot ateletype, then zmore actsjust likezcat, except that a header isprinted before each file 
FILES 

/etc/termeap Terminal database 
SEEALSO 

more(l), gzip(l), zdiff(l), zgrep(l), znew(l), zforce(l), gzexe(l) 

znew 

znew— RecompressZ filesto GZ files 
SYNOPSIS 

znew [ -ftv9PK] [ name.Z ... ] 



zna/v 




DESCRIVO N 

znew recompressesfilesfrom Z (compressi formatto GZ (gzip) format. Ifyou wantto recompressa file al ready in gzip 
format, renarne the fi le to forcea .z extension, then apply znew. 

OPTIONS 



-f Force recompression from Z to GZ format even if a GZ file 

al ready exists. 

-t Test the new files beforedeleting originals. 

-v Verbose. D isplay the nameand percentage reduction for each 

filecompressed. 

-9 Usetheslowestcompression method (opti mal compression). 

-p Usepipesfortheconversion to reducedisk spaceusage. 

■ k Keep aZ file when it issmallerthan theGZ file. 



SEEALSO 

gzip(l), zmore(l), zdiff(l), zgrep(l), zforce(l), gzexe(l), compress(l) 

BUGS 

znew doesnot maintain thetimestamp with the - p option if cpmod(l) is not availableand touch(l) does not support the -r 
option. 
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P art II: System Calls 

intro 

intro— Introduction to system calls 

D ESC RIPTIO N 

T h i s eh apter d escri bes th e L i n ux system cai I s. 

CALLING DIRECTLY 

In most cases, it isunnecessary to invoke a system cali directi y, buttherearetimeswhen the standard C library does not 
implement anice function cali foryou. 

SYNOPSIS 

(finclude <linux/unistd .h> 

A _syscaii macro 
Desired system cali 

SETUP 

The important thing to know about a system cali is itsprototype. You need to know how many arguments, their types, and 
the function return type. Six macrosmaketheactual cali into the system easier. They havetheform 

syscallX(t y pe ,name ,t y pel ,ar gl ,t y p e 2 ,ar g2 , . . . ) 

where 



x 0-5, which are the numberof arguments taken by thesystem cali 

type The return type of thesystem cali 

name The name of the system cali 

typeN TheNth argument'stype 

a r g n T he name of the N th argument 



Thesemacros create a function called name with the arguments you specify. 0 nceyou include_syscallo in your sourcefile, 
you cali thesystem cali byname. 

EXAMPLE 

{ 

struct sysinfo s_info; 
int error; 

error = sysinfo(&s_info) ; 

printf ("code error = %d\n", error); 

printf ( "Uptime = %ds\nl_oad: 1 min %d / 5 min %d / 15 min %d\n" 

"RAM: total %d / free %d / shared %d\n" 

"Memory in buffers = %d\nSwap: total %d / free %d\n" 

"Number of processes = %d\n", 
s_info . uptime, s_info.loads[0] , 
s_inf o . loads[ 1 ] , s_inf o. loads[2 ] , 
sinfo.totalram, s_info.f reeram, 
s_inf o . sharedram, s_inf o . buf f erram , 
s_inf o . totalswap, s_inf o . f reeswap, 
s_info. procs) ; 
return(0) ; 

} 




SAMPLE OUTPUT 

code error = 0 
uptime = 502034S 

Load: 1 min 13376 / 5 min 5504 / 15 min 1152 

RAM: total 15343616 / free 827392 / shared 8237056 

Memory in buffers = 5066752 

Swap: total 27881472 / free 24698880 

Number of processes = 40 

NOTES 

The syscaiio macrosdo not produce a prototype. You might haveto create one, especially for C-H-users. 

System calls are not required to return only positive or negative error codes. You need to read thesourceto besurehow it 
will return errors. Usually, it isthe negative of a standard error code, for example, -eperm. The_syscaiio macroswill return 
theresultr of the system cali when r is nonnegative, but will return -1 and set the variable ermo to -r when r isnegative. 

Somesystem calls, such asmmap, requiremorethan fivearguments. Thesearehandled by pushingtheargumentson thestack 
and passi ng a pointer to the block of arguments. 

When def i ni ng a system cali, the argumenttypes must bepassed by valueor by pointer (foraggregatessuch asstructs). 
FILES 

/usr /include/ linux /unistd . h 

AUTHORS 

Look at theheader of themanual page for the author(s) and copyright conditions. N otethat thesecan bedifferent from page 
to page. 

Linux 1.2.13, 22 May 1996 

exit 

exit— Terminate thecurrent process 
SYNOPSIS 

#include <unistd.h> 
void exit(int status); 

DESCRIPTION 

exit termi nates the cai li ng process immedi ately. Any open fi le descriptors belongi ng to the process areclosed; any children of 
the process are inherited by processi, init, and theprocess'sparent issent a sigchld signal. 

status isreturned to theparent process astheprocess's exit status and can becollected usingoneof thewait familyof calls. 

RETURN VALUE 

exit never returns. 

CONFO RMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

exit does not cali any functions registered with theAN SI C atexit function and does notflush standard I/O buffers. To do 
thesethings, useexit(3). 
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SEEALSO 

fork(2), execve(2), waitpid(2), wait4<2), kill(2), wait(3), exit(3) 

Linux, 21 July 1993 



accept 

accept— Accept a connection on asocket 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/socket.h> 

int accept(int s, struct sockaddr *addr , int *a d d r I en ) ; 

D ESC RIPTIO N 

Thearguments isasocketthat hasbeen createci with socket(2), bound to an addresswith bind(2), and islisteningfor 
connections after a ìisten (2). The accept function extracts the first connection request on thequeueof pending connec- 
tions, createsa new socket with thesamepropertiesof s, and allocatesa new fi le descri ptor for thesocket. If no pending 
connections are present on thequeueand thesocket isnot marked asnonblocking, accept blocks the Caller until a connec- 
tion ispresent. If thesocket ismarked nonblockingand no pending connections are present on thequeue, accept returnsan 
erroras descri bed below. Theaccepted socket may not beused to accept more connections The originai socket s remains 
open. 

Theargumentaddr isa result parameterthat isfilled in with theaddressof theconnecting entity, as known to thecommuni- 
cations layer. The exact format of theaddr parameter is determi ned by the domain in which the communi cation isoccurring. 
T he a dd r i e n is a value-result parameter; itshould initially contai n the amountof space poi nted to by addr ; on return itwill 
contai n theactual length (in bytes) of the ad dress return ed. This cali isused with connection-based socket types, currently 

With SOCK_STREAM. 

It ispossibleto seiect(2) a socket for the purposes of doing an accept by selecting it for read. 

For certain protocolsthat requirean explicit confi rmation, such asiso and datakit, accept can bethought of asmerely 
dequeuing thenext connection request and not implying confirmation. Confi rmation can beimplied by anormal read or 
writeon the new fi le descri ptor, and rejection can beimplied by closing the new socket. 

Onecan obtain user connection request data without confi rming the connection by issuingarecvmsg(2) cali with amsg 
iovien of 0 and a nonzero msg ccntroiien, or by issuingagetsockopt(2) request. Similarly, onecan provide user connection 
rejection information by issuingasendmsg(2) cali providing only the control information, orby calling setsockopt(2). 

RETURN VALUES 

Thecall returns-1 on error. If itsucceeds, it returns a nonnegative i nteger that isa descriptor for the accepted socket. 
ERRORS 

ebadf The descri ptor isinvalid. 

enotsock The descri ptor referencesa file, notasocket. 

eopnotsupp Thereferenced socket isnot of type sock stream. 

efault Theaddr parameter isnot in a writablepart of the user address space. 

ewouldblock T he socket is marked nonblockingand no connecti ons are present to beaccepted. 



HISTORY 

Theaccept function appeared in BSD 4.2. 



access 




SEEALSO 

bind(2), connect(2), listen(2), select(2), socket(2) 

BSD Man Page 24 July 1993 



access 

access— C hecksuser's permissionsfor a file 
SYNOPSIS 

#include <unistd.h> 

int access(const char *p a t h n a me , intmo de); 

DESCRIPTION 

access checks whether the process would beallowed to read, write, or test for exi stenceof thefile {or other file system object) 
whosenameispathname. I f p a t h n a me isa symbolic link, pernii ssionsof the file referred by this symbol ic link aretested. 

mode isa mask consisti ngof oneor moreof r_ok, w_ok, x_ok, and f_ok. 

r_ok, w_ok, and x_ok request checking whether the file exists and has read, write, and execute pernii ssions, respecti vely. f_ok 
just requests checki ng for the existence of the fi le. 

Thetestsdepend on the permissions of the directories occurring i n the path to thefile, asgiven in pattinarne, and on the 
permissions of directories and files referred by symbolic linksencountered on theway. 

The check isdonewith theprocess's real U ID and GID, rather than with theeffectivelDsasisdonewhen actually 
attempting an operation. Thisisto allow set-U I D programsto easily determi ne the invoking user's authority. 

Only access bits are checked, notthefiletypeor contents. Therefore, if a directory isfound to be "writable," it probably 
meansthatfilescan becreated in the directory, and notthat the directory can bewritten asafile Similarly, a DOSfilemay 
befound to be"executable," buttheexecve(2) cali will stili fail. 

RETURN VALUE 

On successali requested permissions granted), a isreturned. On errar (at least 1 bit in mode asked for a permission that is 
denied, or someother errar occurred), -1 isreturned and ermo is set appropri ately. 

ERRORS 

eacces Therequested accesswould bedenied, eitherto thefile itself or one of thedi rectories in 

p a t h n a me . 

efault pattinarne poi nts outside your accessi ble address space. 

einval mode wasincorrectly specified. 

ENAMETOOLONG pat hna me ÌStOO long. 

enoent A directory component in pattinarne would nave beai accessiblebutdoesnotexistorwasa 

dangling symbolic link. 

enotdir A component used as a directory in pathnameisnot, in fact, a directory. 

enomem I naif fi ci ent kernel memory wasavailable. 

eloop pat hna me contains a referenceto a circular symbolic link, that is, a symbolic link contai ni ng 

a referenceto itself. 

RESTRICTIONS 

access returnsan errar ifanyof the access types in therequested cali fails, even if other types might be successful. access may 
notwork correctly on N FS file systems with UID mappingenabled becauseUID mapping isdoneon the server and hidden 
from the client, which checks permissions. 
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CONFORMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

stat(2), open(2), chmod(2), chown(2), setuid(2), setgid(2) 

Linux 1.2.13, 17 March 1996 

acct 

acct— Switches processaccounting on or off 
SYNOPSIS 

#include <unistd.h> 

int acct(const char *f Menarne); 

D ESC RIPTIO N 

Warning: Sincethisfunction isnot implemented asof Linux 0.99.11, itwill always return -1 and set ermo to enosys. If 
acctkit isinstalled, thefunction performsasadvertised. 

When called with thenameof an existi ng file as argument, accounting isturned on and recordsfor each termi nati ng process 
areappended to fi i e n a me asit termi nates. An argument of null causes accounting to beturned off. 

RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned and ermo isset appropriately. 
NOTES 

N 0 accounting isproduced for programsrunningwhen a crash occurs. In parti cular, nontermi nati ng processes are never 
accounted for. 

SEEALSO 

acct(5) 

Linux 0.99.11, 10 August 1993 

adjtimex 

adjtimex— Tuneskernel clock 
SYNOPSIS 

#include <sys/timex.h> 

int adjtimex(struct timex *buf); 

DESCRIPTION 

Linux uses David M ill's clock adjustment algori thm. adjtimex readsand optionally setsadjustment parametersfor this 
algorithm. 

adjtimex takes a pointer to a t mex structure, updates kernel parametersfrom field values, and returns the samestructure with 
current kernel values. This structure isdeclared asfollows: 



adjtimex 



struct timex 



int mode; 
long offset; 
long frequency; 
long maxerror; 
long esterror; 
int status; 
long time_constant; 
long precision; 
long tolerance; 

struct timeval time; 
long tick; 



mode selector */ 

time offset (usec) */ 

frequency offset (scaled ppm) */ 

maximum error (usec) */ 

estimated error (usec) */ 

clock command/status */ 

pll time Constant */ 

clock precision (usec) (read only) */ 

clock frequency tolerance (ppm) 

(read only) */ 

(read only) */ 

usecs between clock ticks */ 



}; 



The no de field determi neswhi eh parameters, if any, to set. It may contai n a bitwi se-or combination of zero or more of the 
following bits: 



#define ADJ OFFSET 



0x0001 /* time offset */ 



#def ine 


ADJ 


FREQUENCY 


0X0002 


/ * 


frequency offset */ 


#def ine 


ADJ. 


MAXERROR 


0X0004 


/ * 


maximum time error */ 


#def ine 


ADJ. 


ESTERROR 


0X0008 


/ * 


estimated time error */ 


#def ine 


ADJ. 


_STATUS 


0X0010 


/ * 


clock status */ 


#def ine 


ADJ. 


TIMECONST 


0x0020 


/ * 


pll time Constant */ 


#def ine 


ADJ. 


TICK 


0X4000 


/ * 


tick value */ 


#def ine 


ADJ. 


OFFSET_SINGLESHOT 


0x8001 


/ * 


old -f ashioned adjtime * 



Ordinary users are restri cted to a 0 value formode. 0 nly thesuperuser may set any parameters. 

RETURN VALUE 

On success, adjtimex retu rns the vai ue of b u f . s t a t u s : 



#define TIME OK 0 /* 
#define TIME INS 1 /• 
#define TIME DEL 2 /• 
#define TIME OOP 3 /• 



clock synchronized */ 
insert leap second */ 
delete leap second */ 
leap second in progress */ 



#define TIME BAD 4 /* clock not synchronized */ 

On failure, adjtimex returns-1 and setserrno. 
ERRORS 



EFAULT 

EPERM 

EINVAL 



buf doesnotpointtowritablememory. 

buf . mode isnonzero and the user isnot superuser. 

An atterri pt is made to set buf . offset to a value outside the range -131071 to +131071, or 
to set buf. status to a value other than those listed above, orto set buf . ti ck to a value 
outsi de the range 900000/H Z to HOOOOO/HZ.whereHZ is the system timer interrupt 
frequency. 



SEEALSO 

settimeofday(2) 



Linux 1.2.4, 15 Aprii 1995 
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alarm 

aiarm— Sets an alarm clock for delivery of a signal 
SYNOPSIS 

#include <unistd.h> 

unsigned int alarm(unsigned int seconds); 

D ESC RIPTIO N 

aia™ arrangesfor a sigalrm signal to beddivered totheprocessin seconds seconds. 

If seconds i s 0, no new aiarm is scheduled. 

In anyevent, any previ ously set aia™ iscanceled. 

RETURN VALUE 

aiarm returns the number of seconds remai ni ng unti I any previ ously scheduled alarm wasdueto bedelivered, oro if there 
wasno previously scheduled alarm. 

NOTES 

aiarm and setitimer share the same timer; Calisto one wi II interfere with useof theother. 
Schedulingdelayscan, asever, cause the execution of theprocessto bedelayed by an arbitrary amount of ti me 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

setitimer(2), signal(2), sigaction(2), gettimeof day(2), select(2), pause(2), sleep(3) 

Linux, 21 July 1993 

bdflush 

bdfiush— Starts, flushes, or tunes the buffer-di rty-flush daemon 
SYNOPSIS 

int bdflush (int fune, long *a d d r e s s ) ; 
int bdflush(int fune, long data); 

DESCRIPTION 

bdfiush starts, flushes, or tunes the buffer-di rty-flush daemon. Onlythesuperuser maycall bdflush. 

If f une is negative oro and no daemon hasbeen started, bdfiush enters the daemon code and never returns. 

If f une is 1 , somedirty buffersarewritten to disk. 

If f une ÌS2 or more and iseven (low bit isO), address istheaddressof a long word, and thetuning parameter numbered 
(f unc-2)/2 isreturned to the Caller in that address. 

If f une ÌS3 or more and isodd (low bit isl), data is a long word and the kernel setstuning parameter numbered (f unc-3)/2 
to that vai ue. 

Thesetof parameters, theirvalues, and their legai rangesaredefined inthe kernel sourcefilefs/buffer.c. 




RETURN VALUE 

If f une is negative oro and thedaemon successfully starts, bdfiush never returns. Otherwise, the return value is a on success 
and -1 on fai Iure, with ermo setto indicate the error. 

ERRORS 

eperm C aller is not superuser. 

efault address points outside your accessible address space. 

ebusy An attempt was madeto enter thedaemon code after another processhasalready been 

entered. 

einval An attempt was madeto read orwritean invalid parameter number, orto writean invalid 

valueto a parameter. 

SEEALSO 

fsync(2), sync(2), update(8), sync(8) 

Linux 1.2.4, 15 Aprii 1995 



bind 

bind— Bindsa nameto asocket 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/socket.h> 

int bind(int sockfd, struct sockaddr *my _ a d d r .intaddr I en ) ; 

DESCRIPTION 

bind givesthesocket, sockfd, the locai address my _ a d d r . my _ a d d r i s a d d r i e n bytes long. Traditionally, thisiscalled assigninga 
nameto asocket. (W hen asocket iscreated with socket(2), it exists in a name space— an addressfamily— but hasno name 
assigned.) 

NOTES 

Bindinga name in theU N IX domain creates a socket i n the fi le system that must bedeleted by the Caller— usi nguniink(2) 
— when it is no longer needed. 

Therulesused in namebinding vary between communication domai ns. Consult themanual entri es in section 4 for detailed 
information. 

RETURN VALUE 

On success, 0 isreturned. On error, -1 isreturned, and ermo isset appropriately. 
ERRORS 

ebadf sockfd isnotavalid descriptor. 

einval The socket i sai ready bound to an address. T hi smay change in the future. Seeiinux/unix/ 

sock.c fordetails. 

eacces The address isprotected and the user is not the superuser. 

Thefollowing errors are specific to UNIX domain (afjjnix) sockets 
einval addr en was wrong, or the socket was not in the afjjnix family. 

erofs Thesocket inodewould resideon a read-only file system. 

efault my _ a d d r points outside your accessible address space. 
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ENAMETOOLONG my a d d r i S tOO long. 

enoent T he file does not exist. 

enomem I naif fi ci ent kernel memory wasavailable. 

enotdir A componentof thepath prefixis not a directory. 

eacces Search permission isdenied on a componentof thepath prefix. 

eloop my^addr contai ns a circular reference (that is, via a symbolic link). 

HI STORY 

Thebind function cali appeared in BSD 4.2. 
SEEALSO 

accept(2), connect(2), listen(2), socket(2), getsockname(2) 

Linux 0.99.11, 23 July 1993 



brk, sbrk 

brk, sbrk— C hange data segment size 
SYNOPSIS 

#include <unistd.b> 

int brk(void *e n d_ d a t a_ s eg me ri t ) ; 

void *sbrk(ptrdiff ti n c r ement ) ; 

DESCRIPTION 

brk setstheend of the data segment to thevaluespecified by end. data, segment . 

endjata_ segment must be greater than the end of thetext segment and it must bel6KB beforetheend of thestack. 
sbrk increments the program's data space byi ncrement bytes. sbrk isn'tasystem cali; it is just a C library wrapper. 

RETURN VALUE 

On success, brk returnsa, and sbrk returns a pointer to the start of thenew area. On errar, -1 isreturned and ermo i s set to 

ENOMEM. 

C0NF0RMST0 

BSD 4.3 

brk and sbrk are not defi ned in the C standard and are deliberately excluded from thePOSIX.l standard (see paragraphs 
B.l.1.1.3 andB.8.3.3). 

SEEALSO 

execve(2), getrlimit(2), malloc(3), end(3) 

Linux 0.99.11, 21 july 1993 



cacheflush 

cachefiush— Flushes contents of the instruction and/or data cache 
SYNOPSIS 



chdir, fchdir 



#include <asm/cachectl.h> 

int cacheflush(char * a d d r , intn by t es , intc a c h e ) ; 

D ESC RIPTIO N 

cachefiush flushescontents of indicateci cache! s) for user addressesin therangeaddr to (addr+nbytes-1). The cache may be 
oneof thefollowing: 

icache Flush the instruction cache. 

dcache Writeback to memory and invali date the affected valid cache li nes. 

bcache Sameas (icache; dcache). 

RETURN VALUE 

cachefiush returnso on success or -1 on errar. If errors are detected, ermo will indicate the error. 
ERRORS 

einval The cache parameter is not oneof icache, dcache, or bcache. 

efault Someorall of theaddressrangeaddr to (addr+nbytes-1) isnot accessible. 

BUGS 

Thecurrent implementation ignorestheaddr and nbytes parameters. Therefore, the whole cache isalwaysflushed. 
NOTE 

Thissystem cali isonly availableon M IPS-based systems. 
SEEALSO 

cachectl(2) 

Linux, 27 J une 95 

chdir, fchdir 

chdir, fchdir— C hanges the working directory 
SYNOPSIS 

#include <unistd.h> 

int chdir(const char *path); 

int fchdir(int f d ) ; 

D ESC RIFTIO N 

chdir changes thecurrent di rectory to that speci fi ed in pa t h. 

fchdir isidentical to chdir, only the directory isgiven asan open file descri ptor. 

RETURN VALUE 

On success, 0 isreturned. 0 n error, -1 isreturned, and ermo isset appropriately. 
ERRORS 

Dependingon the fi le system, other errors can bereturned. The more general errors are li sted here: 
eperm Theprocessdoes not haveexecutepermission on the di rectory. 

efault patti poi nts outside your accessible address space. 

ENAMETOOLONG pat h ÌS tOO long. 
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ebadf fd isnotavalid fi le descri ptor. 

enoent T he file does not exist. 

enomem I naif fi ci ent kernel memory wasavailable. 

enotdir A componentof thepath prefixis not a directory. 

eacces Search permission isdenied on a componentof thepath prefix. 

eloop patti contains a circular reference (that is, via a symbolic link) 

SEEALSO 



getcwd(3), chroot(2) 

Linux 1.2.4, 15 Aprii 1995 



chmod, f chmod 

chmod, fchmod— C hanges perni issions of a file 
SYNOPSIS 

«include <sys/types.h> 

«include <sys/stat.h> 

int chmod(const char *p a t h , modetmo de); 

int fchmod(int f i I des ,modetmode ) ; 

D ESC RIPTIO N 

The mode of the file given bypath orreferenced byfi i edes ischanged. 
M odes are speci fi ed by oring thefollowing: 



SISUID 
S_ISGID 
S_ISVTX 

S_IRUSR (S_IREAD) 

S_IWUSR (s_iwrite) 

SJXUSR (S_IEXEC) 

SIRGRP 

S_IWGRP 

SIXGRP 

S_IROTH 

S_IWOTH 

S IXOTH 



04000 Set user ID on execution 
02000 Set group ID on execution 
01000 Sticky bit 
00400 Read by owner 
00200 Writeby owner 
00100 E xecute/ search by owner 
00040 Read by group 
00020 W rite by group 
00010 E xecute/ search by group 
00004 Read by others 
00002 Writeby others 
00001 E xecute/ search by others 

TheeffectiveU ID of the process must beO or must match theowner of the file. 
TheeffectiveU ID orGID must be appropri atefor setti ng execution bits. 
Dependingonthefilesystem, set user ID and set group ID execution bits may beturned 
off if a fi le is written. On some fi le system s, only thesuperuser can set the sticky bit, which 
may have a special meaning(that is, for directories, a file can only bedeleted by theowner 
or thesuperuser). 



RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 



chown, fchown 

ERRO RS 

D ependi ng on the fi le system, othererrorscan bereturned. The more general errorsfor chmod arelisted here 
eperm TheeffectiveU ID doesnot match the ownerof the fi le and is noto. 

erofs Thenamed fileresideson a read-only file system. 

efault patti poi nts outside your accessible address space. 

ENAMETOOLONG pat h ÌS tOO long. 

enoent Thefiledoes not exist. 

enomem I nsuffi ci ent kernel memory wasavailable. 

enotdir A componentof thepath prefixis not a directory. 

eacces Search permission isdenied on a componentof thepath prefix. 

eloop patti contains a circular reference (that is, via a symbolic link) 

The general errors for f chmod arelisted here: 

ebadf Thedescriptor isnot value. 

enoent See above. 

eperm See above. 

erofs See above. 

SEEALSO 

open(2), chown(2), stat(2) 



Linux 0.99.11, 21 July 1993 



chown, fchown 

chown, fchown— Changesownership of a file 
SYNOPSIS 

#include <sys/types.h> 
#include <unistd.h> 

int chown(const char * p a t h , uid t owner , gid_t group); 

int fchown (int f d , uid t owner, gid_t group); 

D ESC RIFTIO N 

T he ownerof the file specifi ed by patti or by f d ischanged. Only thesuperuser may change the ownerof a fi le. The owner of 
afilemay change the group of the file to any group of which that owner is a member. Thesuperuser may change the group 
arbitrari ly. 

Iftheowner or gr oup isspecified as-1, that I D isnot changed. 
RETURN VALUE 

On success, e isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

D ependi ng on the fi le system, othererrorscan bereturned. The more general errorsfor chown arelisted here 

eperm TheeffectiveUID doesnot match theowner ofthefile, and isnot 0; ortheowner orgroup 

werespecified incorrectly. 
erofs Thenamed fileresideson a read-only file system. 

efault patti pointsoutsideyouraccessibleaddressspace. 
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ENAMETOOLONG p a t h ÌS tOO long. 

enoent T he file does not exist. 

enomem I nsuffi ci ent kernel memory wasavailable. 

enotdir A componentof thepath prefixis not a directory. 

eacces Search permission isdenied on a componentof thepath prefix. 

eloop patti contains a circular reference (that is, via a symbolic link). 

Thegeneral errorsforfchown are I i sted here: 

ebadf Thedescriptor is not value. 

enoent See above. 

eperm See above. 

erofs See above. 

NOTES 



chown does notfollow symbolic links. The prototypefor fchown isonly availableif use bsd isdefined. 
SEEALSO 

chmod(2), flock(2) 

Linux 0.99.11, 21 July 1993 

chroot 

chroot— C hanges root di rectory 
SYNOPSIS 

#include <unistd.h> 

int chroot(const char *path); 

DESCRIPTION 

chroot changes the root directory to that specified in pat h. This directory wi II beused for pathnames beginning with /.The 
root di rectory isinherited byall children ofthecurrent process. 

0 nly the superuser may change the root directory. 

N otethat this cali does not change the current working directory, so that . can beoutsidethetree rooted at /. 
RETURN VALUE 

On success, e isreturned. 0 n errar, -1 isreturned and ermo i s set appropriately. 
ERRORS 

Dependingon the fi le system, other erro rs can bereturned. The more general errors are listed here: 



eperm TheeffectiveU ID doesnot match theowner ofthefile, and is not 0; ortheowner orgroup 

were specified incorrectly. 

erofs Thenamed file resides on a read-only file system. 

efault patti poi nts outside your accessible address space. 

ENAMETOOLONG p a t h ÌS tOO long. 

enoent T he file does not exist. 

enomem I nsuffi ci ent kernel memory wasavailable. 



enotdir A componenti of thepath prefix is nota directory. 

eacces Search permission isdenied on a componentof thepath prefix. 

eloop patti contains a circular reference (that is, via a symbolic link) 



SEEALSO 

chdir(2) 



clone 



Linux 1.1.46, 21 Augii st 1994 



clone 

clone— Createsachild process 
SYNOPSIS 

#include <linux/sched.h> 
#include <linux/unistd.h> 

pid t clone(void *sp, unsigned long flags); 

DESCRIVO N 

clone isan alternate i nterface to fork, with moreoptions. fork isequivalentto cione(0, sigcld|copyvm>. 
If sp is nonzero, thechild process usessp asitsinitial stack pointer. 

Thelow byte of ti ags containsthesignal sent to theparent when thechild dies. ti ags may also bebitwiseored with either or 
both of copyvm and copyfd. 

If copyvm isset, child pages are copy-on-writeimagesof theparent pages. If copyvm isnot set, thechild process shares the sam e 
pagesas theparent, and both parentand child may writeon the same data. 

If copyfd isset, the child's file descriptors are copies of the parent'sfi le descri ptors. I f copyfd isnot set, thechild'sfile 
descri ptors are shared with theparent. 

RETURN VALUE 

On success, the PID of thechild process is returned in theparent'sthread of execution, and 0 isreturned in the child's 
thread of execution. 0 n failure, a -1 will be returned in the parent's context, no child process wi II becreated, and ermo will 
be set appropri ately. 

ERRORS 

enosys clone will always return this errar, unlessyour kernel was compi led with 

clone_actually_works_ok defi ned. 
eagain fork cannot allocate sufficient memory to copy the parent's page tables and allocate a task 

structurefor the child. 

BUGS 

By default, clone_actually_works_ok isnot defi ned. 
There is no entry for clone in /iib/iibc.so.4.5.26. 

Comments in the kernel asof 1.1.46 indicate that it mishandles the case where copyvm isnot set. 
SEEALSO 

fork(2) 

Linux 1.2.9, 10Junel995 
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dose 

dose— Closesa file descriptor 
SYNOPSIS 

«include <unistd.h> 
int closefint f d ) ; 

D ESC RIPTIO N 

dose closes a file descriptor so that it no longer refersto any fi le and may bereused. Any locksheld on the fi le it was 
associated with, and owned by the process, areremoved (regardlessof the fi le descriptor that was used to obtain the lock). 

If f d isthelast copy of a particular fi le descriptor, the resources associated with it arefreed; if the descriptor was the last 
referenceto a fi le that has been removed usinguniink, the fi le is deleted. 

RETURN VALUE 

dose returnse on success, or -1 if an errar occurred. 

ERRORS 

ebadf fd isn't a valid open file descri ptor. 

CONFO RMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

N ot checking the return valueof dose is a common but neverthelessserious programmi ng errar. Fi le system implementa- 
tionsthat use techniquesaswrite- beni nd to increase performance may lead to wr i te (2) succeeding, although the data has not 
been written yet. The error status may be reported at a laterwri te operati on, but it isguaranteed to bereported on closing 
the fi le. N ot checking the return valuewhen closing the fi le may lead to silent lossof data. Thiscan especially beobserved 
with N FS and disk quotas. 

SEEALSO 

open(2), fcntl(2), shutdown(2), unlink(2), fclose(3) 

14 Aprii 1996 

connect 

connect— Initiates a connection on asocket 
SYNOPSIS 

«include <sys/types.h> 
«include <sys/socket.h> 

int connect(int sockfd, struct sockaddr *s er v_ ad d r , inta d d r I en ) ; 

DESCRIPTION 

T he parameter sockfd isasocket. If it i s of type sock_dgram, thiscall specifiesthe peer with which thesocket isto be 
associated; thisaddress isthatto which datagrams areto besent, andtheonlyaddressfrom which datagrams areto be 
received. If thesocket isof type sock_stream, thiscall atterri ptsto make a connection to another socket. Theother socket is 



dup, dup2 



specified by serv_addr, which isan address in the Communications space of the socket. Each Communications space interprets 
the serv_addr, parameter in itsown way. Generally, stream socketsmay successfully connectonly once; datagram sockets 
may useconnect multi pie ti mesto changetheir associ ation. Datagram sockets may dissolve the association by connectingto 
an invalid address, such asa nuli address. 

RETURN VALUE 

If the connection or binding succeeds, 0 isreturned. On error, -1 isreturned and ermo is set appropri atei y. 
ERRORS 

See the Linux kernel source code for details 
HI STORY 

Theconnect function cali first appeared in BSD 4.2. 
SEEALSO 

accept(2), bind(2), listen(2), socket(2), getsockname(2) 

Linux 0.99.11, 23 July 1993 

dup, dup2 

dup, dup2— D uplicate a file descriptor 
SYNOPSIS 

#include <unistd.h> 
int dup(int o I d f d ) ; 
int dup2(int o I df d , intne wf d ) ; 

DESCRIPTION 

dup anddup2 create a copy of the fi le descri ptor o i df d. 

Theold and new descri ptorscan beused interchangeably. They sharelocks, file position pointersand flags; for example, if 
thefile position ismodified by using iseek on oneof the descri ptors, the position isalso changed fortheother. 

Thetwo descriptorsdo not sharetheclose-on-exec flag, however. 

dup usesthelowest-numbered unused descri ptor for the new descriptor. 

dup2 makesnewfd bethecopy of oi dfd, closingnewf d first if necessary. 

RETURN VALUE 

dup and dup2 return the new descriptor, or -1 if an error occurred (in which case ermo isset appropriately). 
ERRORS 

ebadf oidfd isn't an open filedescriptor, ornewf d is out of the allowed rangefor file descriptors. 

emfile Theprocessalready has the maximum numberof fi le descri ptors open and tried to open a 

new one. 

WARNING 

The error returned by dup2 isdifferentfrom that returned by tenti (. . ..fjdupfd, . . .) when newf d isout of range On some 
systems dup2 also sometimes returns einval li ke f_dupfd. 
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CONFORMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

fcntl(2), open(2), close(2). 

Linux 1.1.46, 21 August 1994 

execve 

execve— Execute program 
SYNOPSIS 

#include <unistd.h> 

int execve (const char * f i I e r a me , const char *argv [], const char *e n v p [ ] ) ; 

D ESC RIPTIO N 

execve o executes the program pointed to by f i i e n a me . f i i e n a me must beeither a binary executableor ashell script starti ng 

with a line in theformat #! i nterpreter [arg]. 

execve o does not return on success, and thetext, data, bss, and stack of the cai li ng processareoverwritten by that of the 
program loaded. The program invoked inherits the cali ing process'sPID, and any open filedescriptorsthat are not set to 
closeon exec. Signalspendingon theparent processarecleared. 

If thecurrent program isbeingptraced, a sigtrap issentto it after a successful execveo. 
RETURN VALUE 

On success, execveo does not return; on errar -1 isreturned and ermo is set appropri ately. 



ERRORS 




EACCES 


Thefileisnotaregular file 


EACCES 


Execute permission isdenied forthefile 


EPERM 


Thefile system ismounted noexec. 


EPERM 


The fi le system is mounted nosui d and thefilehasan SUID or SGID bit set. 


E2BIG 


Theargument list istoo big. 


ENOEXEC 


The magic number in thefile isincorrect. 


E FAULT 


f i i e n a me poi nts outside your accessi bleaddress space. 


ENAMETOOLONG 


f i I ename istOO long. 


ENOENT 


Thefiledoesnot exist. 


ENOMEM 


I nsuffi ci ent kernel memory wasavailable. 


ENOTDIR 


A component of the path prefix is not a directory. 


EACCES 


Search permission isdenied on a component of the path prefix. 


ELOOP 


f m ename contains a circular reference (that is, via a sym bolic link). 



CONFORMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

SUID and SGID processescan not beptraceo'd SUID or SGID. 




A maximum linelength of 127 eh aracters i s al I o wed for the first line in a #i executable shell script. T hi smay becircum- 
vented by changing themaxsizeof buf, in which caseyou will becomebound by the 1024 bytesizeof a buffer, which isnot 
easily worked around. 

SEEALSO 

execl(3), fork(2) 

Linux 1.1.46, 21 August 1994 



fcntl 



F DUPFD 



fcnti— M anipulate file descri ptor 
SYNOPSIS 

#include <unistd.h> 

«include <fcntl.h> 

int fcntl(int f d , intc md ) ; 

int fcntl(int f d , intc md , longa r g ) ; 

DESCRIVO N 

tenti performsoneof various miscellaneous operati ons on fd. The operati on in question is determi ned by c md : 

Maksarg be a copy of f d , closingfd first if necessary. 
T he same funzionali ty can be more easily achieved by using dup2(2). 
The old and new descri ptors may beused interchangeably. They sharelocks, fi le position 
pointers, and flags; for example, if the fi le position ismodified by using iseek on oneof the 
descriptors, theposition isalso changed fortheother. 
Thetwo descriptors do not sharetheclose-on-exec flag, however. 
0 n success, the new descri ptor is returned. 

Read theclose-on-exec flag. If the low-order bit isO, the fi le will remai n open acrossexec; 
otherwise, itwill beclosed. 

Set theclose-on-exec flag to the vai ue specified by arg (only the least significant bit 
isused). 

Read the descri ptor's flags (ali flags— asset by open(2)— are returned). 
Set the descri ptor's fi agsto the value specified by a r g . 
0 nly o append and o_nonblock may be set. 

Theflags areshared between copies(madewith dup and so on) of the same file descri ptor. 
T he flags and thei r semantics are descri bed i n open(2). 

M anage discreti onary filelocks. Thethird argument arg isa pointerto astructflock 
(that may beoverwritten by this cali). 

Return theflock structurethat preventsusfrom obtainingthelock, or set the ì type field of 
thelockto fjjnlck if thereisno obstruction. 

Thelock isset (when ì type is f_rdlck or f_wrlck) or cleared (when it is f_unlck). 
If thelock isheld by someoneelse, this cali returns -1 and setserrno to eacces or eagain. 
Like f_setlk, but instead of returni ng an errar, wewait for thelock to bereleased. 
G et the process I D (or process group) of the owner of a socket. 
Processgroups are returned as negative vai ues. 
Set the process or process group that owns a socket. 
Forthesecommands, ownership meansreceiving sigio or sig-urg signals. 
Processgroups are specified using negati ve vai ues 



F GETFD 



F SETFD 



F_GETFL 
F SETFL 



F_GETLK, F_SETLK, 

and f_setlkw 

F GETLK 



F SETLK 



F_SETLKW 
F GETOWN 



F SETOWN 




Part II: System Calls 



RETURN VALUE 

The return value depends on theoperation: 

f_dupfd Thenew descriptor. 

f_getfd Value off lag. 

f_getfl Valueof flags. 

f_getown Valueof descriptor owner. 

On error, -1 isreturned and ermo is set appropri atdy. 
ERRORS 

ebadf fd isnotan open file descriptor. 

einval For f_dupfd, arg is negative or isgreater than the maximum allowable value. 

emfile For f_dupfd, the process al ready has the maxi mum number of f i le descri ptors open. 

NOTES 

Theerrors returned by dup2 aredifferentfrom thosereturned by f_dupfd. 
CONFO RMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

dup2(2), open(2), socket(2). 

Linux, 26 September 1995 



fdatasync 

tdatasync— Synchronizes afile's in-core data with that on disk 



SYNOPSIS 

#include <unistd.h> 
ffifdef POSIX SYNCHRONIZED IO 
int fdatasync(int f d ) ; 
#endif 



DESCRIPTION 

tdatasync flushes al I data buffersof afileto disk (before the system cali returns). It resemblesfsync but isnot required to 
update the metadata such as access ti me. 

Appi ications that access databases or log fi lesoften writeatiny data fragment (for exam pie onelinein a log fi le) and then 
cali fsync immedi ately in order to ensurethat thewritten data is physically stored on the hard disk. U nfortunately, fsync will 
always initiatetwo w ri te operati ons: onefor thenewly written data and another onein order to update the modification ti me 
stored in the i node. If the modification time is not a part of thetransaction concept tdatasync can be used to avoid 
unnecessary inode disk writeoperations 

RETURN VALUE 



O n success, 0 is returned. 0 n error, -1 isreturned and ermo is set appropriately. 



flock 



ERRO RS 

ebadf fd is not a valid fi le descriptor open for writi ng. 

erofs, einval fd is bound to a special file which does not support s/nchronization. 

eio An errar occurred during synchronization. 

BUGS 

Currently (Linux 1.3.86) fdatasync isequivalent to fsync. 
C0NF0RMST0 

POSIX.4 

SEEALSO 

fsync(2), B.O . Gallmeister, POSIX.4, 0 'Rally, pp. 220-223, 343. 

Linux 1.3.86, 13 Aprii 1996 



flock 

fiock— Appliesorremovesan advisory lock on an open file 
SYNOPSIS 

#include <sys/file.h> 

int flock(int fd.intoperation) ; 

DESCRIPTION 

Apply or remove an advisory lock on an open file. The file isspecified by f d. Valid operati ons are given here 



lock_sh Shared lock. M orethan oneprocessmay hold ashared lock for agiven file at a given time. 

lock_ex Exclusivelock. Only oneprocessmay hold an exclusive lock for agiven fi le at agiven time 

lockjjn Unlock. 

lock_nb Don't block when locking. M ay bespecified (by oring) along with oneof theother 



operati ons. 

A singlefilemay not haveboth shared and exclusive locks. A fileislocked (that is, the 
inode), not the file descriptor. So, dup(2) and fork(2) do not create multi pie instances 
of a lock. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

ewouldblock Thefileis locked and the lock_nb flag wasselected. 

NOTES 

U nder Linux, fiock isimplemented asacall to tenti. Pleaseseetcnti(2) for moredetailson errors. 
SEEALSO 

open(2), close(2), dup(2), execve(2), fcntl(2), fork(2) 

Linux 0.99.11, 22 July 1993 
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fork, vfork 

f ork, vfork— C reates a chi Id process 
SYNOPSIS 

#include <unistd.h> 
pid t fork(void) ; 
pid t vfork(void) ; 

DESCRIPTION 

fork creates a eh i I d process that differs from theparent process only in itsPID and P PID , and in thefact that resource 
uti lizations are set to e. F ile locks and pendi ng signals are not i nherited. 

U nder Linux, fork isimplemented using copy-on-writepages, so the only penalties incurred by fork are the ti me and 
memory required to duplicate the parent's page tables and to create a uni que task structurefor the chi Id. 

RETURN VALUE 

On success, the PID of the chi Id process is returned in the parent's thread of execution, and ao isreturned in thechild's 
thread of execution. 0 n failure, a -1 will be returned in the parent's context, no child process wi II becreated, and ermo will 
be set appropri ately. 

ERRORS 

eagain fork cannot allocate suffi ci ent memory to copy the parent's page tables and allocate a task 

structurefor the child. 

BUGS 

U nder Linux, vfork ismerely an alias forfork. fork never returns the errar enomem. 
CONFO RMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

clone(2), execve(2), wait(2) 

Linux 1.2.9, 10 Junel995 

fsync 

fsync— Synchronizesafile's complete in-core state with that on disk 
SYNOPSIS 

#include <unistd.h> 
int f sync(int f d ) ; 

DESCRIPTION 

fsync copi esali in-core partsof afileto disk. 

In someapplications, fdatasync isa more efficient alternative to fsync. 

RETURN VALUE 

O n success, 0 is returned. 0 n errar, -1 is returned and ermo isset appropriately. 



getdents 




ERRO RS 

ebadf fd is not a valid fi le descriptor open for writi ng. 

erofs, einval fd is bound to a special file that does not support synchronization. 

eio An errar occurred during synchronization. 

C0NF0RMST0 

POSIX.lb 

SEEALSO 

bdflush(2), fdatasync(2), sync(2), update(8), sync(8) 

Linux 1.3.85, 13 Aprii 1996 



getdents 

getdents— Gets directory entri es 



SYNOPSIS 

#include <unistd.h> 
#include <linux/dirent.h> 
#include <linux/unistd.h> 

syscall3(int, getdents, uint, fd, struct dirent *, dirp, uint, count); 
int getdents(unsigned int fd, struct dirent *dirp, unsigned int count); 

D ESC RIPTIO N 

getdents readsseveral dirent structuresfrom the directory pointed at byf d into the memory area poi nted to by di r p. The 
param eter court i s the size of the m emory area. 

T he d rem structure is declared asfollows: 

struct dirent 

{ 

long d_ino; /* inode number */ 

off_t d_off; /* offset to next dirent */ 

unsigned short d_reclen; /* length of this dirent */ 

char donarne [NAME_MAX+1 ] ; /* file name (null-terminated) */ 

} 

dj no isan inode number. d_ of f isthedistancefrom the start of the directory to the start of the next di rent . d _ r e c i en isthe 
si zeof this enti re dirent. donarne is a null-terminated filmarne. 

This cali supersedes readdir(2). 
RETURN VALUE 

On success, the number of bytesread is returned. On end of directory, 0 isreturned. On errar, -1 isreturned and ermo isset 
appropri atei y. 

ERRORS 

ebadf Invalid filedescriptorf d. 

enotdir F i le descri ptor does not refer to a di rectory. 

SEEALSO 

readdir(2), readdir(3) 



Linux 1.3.6, 22 July 1995 




P art II: System Calls 



getdomainname, setdomainname 

getdomainname, setdomainname— G ets/sets domain name 

SYNOPSIS 

#include <unistd.h> 

int getdomainname(char *name, size_t en); 

int setdomainname(const char *name, sizejt I e n ) ; 

DESCRIPTION 

Thesefunctionsareused to accessorto change the domain name of the current processor. 
RETURN VALUE 

0 n success, 0 is returned. 0 n errar, -1 is returned and ermo isset appropriately. 
ERRORS 

EINVAL For getdomainname, name pointStO NULL Or name ÌS longer than I en . 

eperm For setdomainname, the Caller was not the superuser. 

EINVAL For setdomainname, I en wastOOlong. 

C0NF0RMST0 

PO SIX does not specify these calls. 

BUGS 

getdomainname is not compliant with other implementations becausethey always return i en bytes, even if name is longer. 
Linux, however, returnsEiNVAL in th i s case (as of DLL 4.4.1 libraries). 

NOTES 

U nder Linux, getdomainname is implemented at the library level by calling uname(2). 
SEEALSO 

gethostname(2), sethostname(2), uname(2) 

Linux 0.99.11, 22 July 1993 

getdtablesize 

getdtabiesize— G ets descri ptor table size 
SYNOPSIS 

#include <unistd.h> 
int getdtablesize(void) ; 

DESCRIPTION 

getdtabiesize returnsthemaximum number of filesa processcan haveopen. 
NOTES 

getdtabiesize is implemented as a library function in DLL 4.4.1. Thisfunction returnsoPENjAx (setto 256 in Linux 
0.99.11) if open_max wasdefined when thelibrary wascompiled. Otherwise, -1 is returned and ermo isset to enosys. 



getgroups, setgroups 



SEEALSO 

close(2), dup(2), open(2) 

Linux 0.99.11, 22 July 1993 

getgid, getegid 

getgid, getegid— Getsgroup identity 

SYNOPSIS 

#include <unistd.h> 
gid_t getgid(void) ; 
gid_t getegid(void) ; 

D ESC RIPTIO N 

getgid returns the real group ID of thecurrent process. 
getegid returnstheeffectivegroup ID of thecurrent process. 

Thereal ID correspondsto thelD of the cai li ng process. T he effettive I D correspondsto theset ID PitonthefilePeing 
executed. 

ERRO RS 

These functions are always successful . 
C0NF0RMST0 

POSIX, BSD 4.3 

SEEALSO 

setregid(2), setgid(2) 

Linux 0.99.11, 23 July 1993 



getgroups, setgroups 

getgroups, setgroups— GetS/setS group access list 

SYNOPSIS 

#include <unistd.h> 

int getgroups ( int s i z e , gid_t I i s t [ ] ) ; 

#define_USE_BSD 

#include <grp.h> 

int setgroups (size_t size, const gid_t *list); 



DESCRIPTION 

getgroups U p to si ze supplemental groups are returned iniist.lfsizeiso, list isnot modified, but 

the total numberof supplemental groups for the process is returned. 
setgroups Setsthesupplemental groups for the process. Only the superuser may usethisfunction. 
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RETURN VALUE 

getgroups 
setgroups 

ERRORS 

E FAULT 
EPERM 
EINVAL 

CONFO RMSTO 

getgroups conformsto POSIX.l (and is present in BSD 4.3). Since setgroups requires privi lege, it isnot coverai under 
POSIX.l. 

BUGS 

The use bsd flag probably shouldn't berequired for setgroups. 
SEEALSO 

initgroups(3) 



On success, thenumber of groupsstored in list isreturned (if si ze is 0, however, the 
number of supplementi group IDsassociated with the process isreturned). 0 n errar, -1 is 
returned and ermo is set appropri atei y. 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 



i st hasan invalid address. 
For setgroups, theuser isnot the superuser. 
For setgroups, gì d s e t si ze isgreater than ngroups (32 for Linux 0.99.11). 



Linux 0.99.11, 23 July 1993 



gethostid, sethostid 

gethostid, sethostid— G ets/sets the unique identifier of thecurrent host 
SYNOPSIS 

#include <unistd.h> 

long int gethostid(void) ; 

int sethostid(long int hostid); 

DESCRIPTION 

Get or set a unique 32- bit identifier for thecurrent machine. The 32-bit identifier isintended to be unique among ali U N IX 
systems in existence. Thisnormally resembles the Internet address for the locai machine, as returned by gethostbyname(3), 
and thus usuai ly never needsto beset. 

The sethostid cali is restri cted to the superuser. 

The h 0 s t i d argument isstored in thefile /etc/hostid. 

RETURN VALUES 

gethostid returns the 32-bit identifier for the current host as set by sethostid(2). 
CONFORMSTO 

POSIX.l doesnotdefinethesefunctions, butlSO/IEC 9945-1:1990 mentionsthem in B.4.4.1. 
FILES 



/etc/hostid 



geti timer, setiti mer 

SEEALSO 

hostid(l), gethostbyname(3) 

Linux 0.99.13, 29 N ovember 1993 

gethostname, sethostname 

gethostname, sethostname— G ets/sets hOStname 

SYNOPSIS 

#include <unistd.h> 

int gethostname(char "nanie, size_t len); 

int sethostname (const char *name, size_t len); 

D ESC RIPTIO N 

Thesefunctionsareused to access orto changethehostnameof thecurrent processor. 
RETURN VALUE 

On success, 0 isreturned. On error, -1 isreturned and ermo isset appropriately. 
ERRORS 

einval i en is negati ve or, for sethostname, largerthan the maximum allowed size For gethostname 

on Linux/i386, i en is smaller than theactual size. 
eperm For sethostname, the Caller was not the superuser. 

efault name isan invai id address. 

CONFO RMSTO 

POSIX.l doesnotdefinethesefunctions, butlSO/IEC 9945-1:1990 mentionsthem in B.4.4.1. 
BUGS 

Someother implementationsof gethostname successfully return 1 en byteseven if name is longer. Linux/Alpha compii eswith 
this behavior. Linux/i386, however, returnsEiNVAL in thiscase(asof D LL 4.6.27 libraries). 

NOTES 

U nder Linux/Alpha, gethostname isasystem cali. U nder Linux/i386, gethostname isimplemented at the li brary leve! by 

callinguname(2). 

SEEALSO 

getdomainname(2), setdomainname(2), uname(2) 

Linux 1.3.6, 22 July 1995 

getitimer, setitimer 

getitimer, setitimer— G ets/sets value of an interval timer 
SYNOPSIS 

#include <sys/time.h> 

int getitimer (int which, struct itimerval *value); 

int setitimer(int wh i c h , conststruct itimer-val * v a I u e , struct itimerval *ovalue); 
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Thesystem provi deseach processwith three interval timers, each decrementing in a distinct timedomain. When any timer 
expires, a signal issent to theprocess, and thetimer (potenti al ly) restarts. 

itimer_real D ecrements i n real timeand deliverssiGALRM upon expiration. 

itimerj/irtual D ecrements only when the processi sexecuting, and deli vers sigvtalrm upon expiration. 

itimer_prof D ecrements both when the process executes and when the system isexecutingon behalf of 

theprocess. Coupled with itimer_virtual, this timer isusually used to proti le the time 
spent by the application in user and kernel space, sigprof isdelivered upon expiration. 

T imer values are defi ned by the foli owi ng structures: 

struct itimerval { 

struct timeval it_interval; /* next value */ 
struct timeval it_value; /* current value */ 

>; 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 

}; 

getitimer(2) fills the structure i ndicated by vai ue with the current setti ngfor thetimer indicated by wh i eh (oneof 
itimer_real, itimerj/irtual, or itimer_prof). T he element it_vaiue isset to the amount ottime remai ni ng on thetimer, or 
0 if thetimer isdisabled. Similarly, it_intervai isset to the reset value. setitimer(2) sets the indicated timer to the value in 
vai u e. If ovai ne isnonzero, the old value of thetimer isstored there. 

Timersdecrement from i t _ v a i u e to 0, generate a signal, and resetto i t_i ntervai . A timerthat isset to 0 (i t _ v a 1 ue iso or the 
timer expires and tj ntervai i s 0) stops. 

Bothtv_sec andtv_usec are signifi cant in determining the duration of atimer. 

Timerswill never expire before the requested ti me, instead expiring some short, Constant ti me afterward, dependent on the 
system timer resolution (currently lOms). U pon expiration, a signal will begenerated and thetimer reset. If thetimer expires 
whiletheprocessisactive(alwaystrueforiTiMER_viRT), the si gnal will bedelivered immediately when generated. Otherwise, 
the delivery will be offset by a small ti me dependent on thesystem loading. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

efault value and ovai ue arenotvalid pointers. 

EINVAL which ÌSnOtOneof ITIMER_REAL, ITIMER_VIRT, Or ITIMERJ'ROF. 

SEEALSO 

gettimeofday(2), sigaction(2), signal(2) 

BUGS 

Under Linux, thegeneration and delivery of a signal are distinct and there each signal ispermitted only oneoutstanding 
event. It's therefore conceivablethat under pathologically heavy loading, itimer_real will expire before the si gnal from a 
previ ous expiration hasbeen del ivered. Thesecond signal in such an eventwill belost. 

Linux 0.99.11, 5 August 1993 



getpeername 

getpagesize 

getpagesize— Gets system pagesize 
SYNOPSIS 

#include <unistd.h> 
size_t getpagesize(void) ; 

DESCRIVO N 

Returnsthenumber of bytes in a page. Thisis the system 's pagesize, which isnot necessari ly the sameas the hardware page 
size. 

NOTES 

getpagesize is implemented as a library function in DLL 4.4.1. D ependi ng on what isdefined when the library is compi led, 
thisfunction returns exec_pagesize (setto 4096 in Linux 0.99.11), nbpg (setto 4896 in Linux 0.99.11), or nbpc (not defined in 
Linux 0.99.11 or D LL 4.4.1 libraries). 

SEEALSO 

sbrk(2) 

Linux 0.99.11, 23 July 1993 

getpeername 

getpeername— G ets the name of the connected peer 
SYNOPSIS 

int getpeername (int s, struct sockaddr *n a me , int*n a me I e n ) ; 

DESCRIPTION 

getpeername returns the name of the peer connected to sockets . The name en parameter should beinitialized to indicate the 
amount of space poi nted to by name. On return it contai ns the actual size of the name return ed (in bytes). The name is 
truncated if thebuffer provi ded istoo small. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

ebadf Thearguments isnot a valid descriptor. 

enotsock Thearguments is a file, not a socket. 

enotconn Thesocket isnot connected. 

enobufs Insufficient resourceswereavailablein thesystem to perform theoperation. 

efault The name parameter pointsto memory not in a valid part of the process address space. 

HI STORY 

The getpeername function cali appeared in BSD 4.2. 
SEEALSO 

accept(2), bind(2), getsockname(2) 

BSD Man Page, 24 July 1993 
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getpid, getppid 

getpid, getppid— Gets process i denti fi cati o n 
SYNOPSIS 

#include <unistd.h> 
pid t getpid (void) ; 
pid_t getppid(void) ; 

DESCRIVO N 

getpid returns the process ID of thecurrent process. (Thisisoften used by routinesthatgenerateuniquetemporary 
filenames) 

getppid returnsthe process ID of the parentof thecurrent process. 
C0NF0RMST0 

POSIX, BSD 4.3, SVID 

SEEALSO 

exec(2), fork(2), kill(2), mkstemp(3), tmpnam(3), tempnam(3), tmpfile(3) 

Linux 0.99.11, 23 July 1993 

getpriority, setpriority 

getpriority, setpriority— G ets/sets program scheduling priority 
SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

int getpriority(int wh i eh, int who); 

int setpriority(int wh i eh, int who, int prio); 

DESCRIPTION 

The scheduling priority of the process, process group, or user, as indicated by whi eh and who, isobtained with the getpriority 
cali and set with the setpriority cali, whi eh isoneof prio_process, PRio_PGRP,or priojjser, and who isinterpreted relative to 
whi eh (a process identifierfor prio_process, process group identifierfor prio_pgrp, and a user ID for priojjser). A 0 valueof 
who denotes thecurrent process, process group, or user, prio is a value in the range -20 to 20. The default priority isO; lower 
priorities cause more favorable scheduling. 

The getpriority cali returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The 
setpriority cali sets the priori ti es of ali the specified processes to the specified value. Only thesuperuser may lower priorities. 

RETURN VALUES 

Because getpriority can legi ti mately return the value -1, it isnecessary to clear the extern al vari able ermo prior to the cali, 
and then check it afterward to determi ne whether a -1 isan error or a legiti mate value. The setpriority cali returns 0 if there 
isno error, or -1 if there is. 

ERRORS 

esrch N 0 process waslocated usingthewhi eh and who values specified. 

EINVAL wh i c h WaS nOt One Of PRIO_PROCESS, PRIO_PGRP,Or priojjser. 



getrlimit, getrusage, setrlimit 



In addition to theseerrors, setpriority will fail with thefollowing: 

eperm A processwaslocated, but neither its effective nor real userID matched theeffectiveuser ID 

of the Caller. 

eacces A nonsuperuser attempted to lower a process priority. 

HI STORY 

Thesefunction callsappeared in BSD 4.2. 
SEEALSO 

nice(l), fork(2), renice(8) 

BSD Man Page, 24 J uly 1993 

getrlimit, getrusage, setrlimit 

getriimit, getrusage, setrlimit— G et/set resource li mits and usage 
SYNOPSIS 

#include <sys/time.h> 
(finclude <sys/resource.h> 
#include <unistd.h> 

int getrlimit (int resource, struct rlimit *rlim); 

int getrusage (int who, struct rusage *u s a g e ) ; 

int setrlimit (int resource, const struct rlimit *r!im); 

D ESC RIPTIO N 

getrlimit and setrlimit get and set resource li mits. resource should beone of thefollowing: 

RLIMIT CPU /* CPU time in seconds */ 

RLIMIT FSIZE /* Maximum filesize */ 

RLIMIT DATA /* max data size */ 

RLIMIT STACK /* max stack size */ 

RLIMIT CORE /* max core file size */ 

RLIMIT RSS /* max resident set size */ 

RLIMIT NPROC /* max number of processes */ 

RLIMIT NOFILE /* max number of open files */ 

RLIMIT MEMLOCK /* max locked-in-memory address space*/ 

A resource may beunlimited if you set the li mit to rlim_infinity. rlimit_ofile is the BSD namefor rlimit_nofile. 
The rlimit structure is defined asfollows: 

struct rlimit 
{ 

int rlim_cur; 
int rlimjnax; 

}; 

getrusage return s the current resource usages for a «ho of either rusage_self or rusage_children: 



struct rusage 
{ 



struct timeval ru_utime; /* user time used */ 

struct timeval ru_stime; /* system time used */ 

long ru_maxrss; /* maximum resident set size */ 

long ru_ixrss; /* integrai shared memory size */ 
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long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 
long 



ru__idrss; 

ru_isrss; 

ru_minf lt ; 

ru_majflt; 

ru_nswap; 

ru_inblock; 

ru_oublock; 

ru_msgsnd; 

ru_msgrcv; 

ru_nsignals; 

ru_nvcsw; 

ru nìvcsw; 



* integrai unshared data size */ 

* integrai unshared stack size */ 

* page reclaims */ 

* page faults */ 

* swaps */ 

* block input operations */ 

* block output operations */ 

* messages sent */ 

* messages received */ 

* signals received */ 

* voluntary context switches */ 

* involuntary context switches */ 



}; 



RETURN VALUE 

On success, 0 isretumed. On errar, -1 isreturned and ermo isset appropriately. 



ERRORS 

EINVAL 
EPERM 

CONFO RMSTO 

BSD 4.3 

SEEALSO 

ulimit(2), quota(2) 



getrlimit Or setrlimit ÌS Called with a bad r es ou r c e . getrusage ÌS Called with a bad wh c . 

A nonsuperuser triesto use setrlimit 0 to increase the soft or hard limit abovethecurrent 
hard limit, or a superuser triesto increase rlimit_nofile abovethecurrent kernel maximum. 



Linux, 23 July 1993 



getsid 

getsid— Getssession ID 
SYNOPSIS 

#include <unistd.h> 
pid_t getsid (void) ; 

DESCRIPTION 

getsido) returnsthesession ID of the cali i ng process. getsid(p) returnsthesession ID of the process with processID p. 
ERRORS 

On errar, -1 will bereturned. The only errar thatcan happen ìsesrch, when no processwith processID p wasfound. 

C0NF0RMST0 

Thiscall is Linux specific. 

SEEALSO 

setsid(2) 

Linux 1.3.85, 11 Aprii 1996 



getsockname 

getsockname— G ets socket name 
SYNOPSIS 

int getsockname (int s ", struct sockaddr *" name ", int *" namelen ); 

DESCRIVO N 

getsockname returns the current name for the specified socket. Thenamei en parameter should beinitialized to indicate the 
amountof space poi nted to byname. On return itcontainstheactual sizeof the name return ed (in bytes). 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

ebadf Thearguments isnot a valid descriptor. 

enotsock Thearguments is a file, nota socket. 

enobufs Insufficient resourceswereavailablein thesystem to perform theoperation. 

efault The name parameter pointsto memory not in a valid part of the processaddress space. 

HI STORY 

The getsockname function cali appeared in BSD 4.2. 
BUGS 

N amesbound to socketsin theLI N IX domain are inaccessi ble; getsockname returns a 0-length name. 
SEEALSO 

bind(2), socket(2) 

BSD Man Page, 24 J uly 1993 

getsockopt, setsockopt 

getsockopt, setsockopt— G et and setoptionson sockets 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/socket.h> 

int getsockopt (int s , int evel , intopt name ,void*opt vai ,int*opt I en ) ; 

int setsockopt (int s ,intl evel , intopt name , const void *opt vai , intopt I en ) ; 

DESCRIPTION 

getsockopt and setsockopt mani pulate the 0 pt ons associated with a socket. Optionsmay exist at multiple protocol levels; 
they are always present at the uppermost socket level. 

When manipulating socket opti ons, the level at which the opti on residesand the name of the option must be specified. To 
mani pulate opti ons at the socket level, 1 evel is specified assoi__socKET. To mani pulate opti ons atany other level, the protocol 
numberof the appropriate protocol controlling the option issupplied. Forexample to indicate that an option isto be 
interpreted bytheTCP protocol, 1 ève should be setto the protocol numberofTCP; seegetprotoent(3). 



getsockopt, setsockopt 
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Theparametersoptva and opti e n areused to access option valuesfor setsockopt. For getsockopt they identify a buffer in 
which thevaluefortherequested option(s) isto bereturned. For getsockopt, opti en isavalue-result parameter, initially 
containingthesizeof the buffer pointed to byoptvai , and modified on return to indicate the actual sizeof thevalue 
returned. If no option valueisto besupplied or returned, opt vai may beNULL. 

o p t n a me and any specified opti ons are passed uninterpreted to the appropriate protocol modulefor interpretation. The 
includefile<sys / socket . h> contai nsdefinitions for socket-level options, described below. 0 ptionsat other protocol levels 
vary in format and name; consult the appropriate entri es in section 4 of themanual. 

M ost socket-level options utilizean i nt parameter for opt vai . For setsockopt, the parameter should be nonzero to enablea 
boolean option, orO if theoption isto bedisabled. so_linger usesastmct unger parameter, defined in <i i nux/ socket . h>, 
which specifies the desi red state of theoption and thelinger interval (see below). so_sndtimeo and so_rcvtimeo useastr net 
tìmevai parameter, defined in <sys/ ti me. h>. 

Thefollowing options are recognized at the socket level. Except as noted, each may beexamined with getsockopt and set 

with setsockopt: 



SO 


DEBUG 


Enables recordi ng of debugging information. 


so 


REUSEADDR 


Enables locai address reuse. 


so 


KEEPALIVE 


Enableskeep connections alive. 


so 


DONTROUTE 


Enables routi ng bypass for outgoi ng messages. 


so 


UNGER 


Unger on dose if data present. 


so 


BROADCAST 


Enables permission to transmit broadcast messages. 


so 


OOBINLINE 


Enables reception of out-of-band data in band. 


so 


SNDBUF 


Sets buffer size for output. 


so 


RCVBUF 


Sets buffer size for input. 


so 


SNDLOWAT 


Sets minimum count for output. 


so 


RCVLOWAT 


Sets minimum count for input. 


so 


SNDTIMEO 


Sets time-out valuefor output. 


so 


RCVTIMEO 


Sets time-out valuefor input. 


so 


TYPE 


Gets thetype of the socket (get only). 


so 


ERROR 


G ets and clears errar on the socket (get only). 



so debug enables debugging in theunderlying protocol modules. 

so_reuseaddr indicates that the rules used in validating addresses supplied in abind(2) cali should allow reuse of locai 
addresses. 

so_keepalive enables the periodic transmission of messages on aconnected socket. Should theconnected party fail to 
respond to these messages, the connection isconsidered broken and processes usi ng the socket are notiti ed viaasiGPiPE 
signal when attemptingto send data. 

so_dontroute indicates that outgoi ng messages should bypass the standard routi ng faci li ti es. Instead, messages are di rected to 
the appropriate network interface accordingto the network portion of the destination address. 

so_linger controis the action taken when unsent messages are queued on socket and aciose(2) isperformed. If the socket 
promises rei iable delivery of data and so_linger isset, the system will block the processon the dose attempt unti I it isableto 
transmit the data or unti I it decides it isunableto deli ver the information (a time-out period, termed thelinger interval, is 
specified in the setsockopt cali when so_linger isrequested). If so_linger isdisabled and acloseisissued, the system will 
process the dose i n a manner that allows the process to conti nue as quickly as possi ble. 

Thei i nger structure is defined in <i i nux/socket h> asfollows: 

struct linger { 

int l_onoff; /* Linger active */ 

int l_linger; /* How long to linger for */ 

}; 



getsockopt, setsockopt 




i_onoff indicates whether to linger. If it is set to 1, i_iinger contai ns the ti me in hundredths of seconds how long the process 
should lingerto complete the dose. If i_onoff is setto 0, the process returnsimmediately. 

Theoption so_broadcast requests permission to send Proadcast datagramson thesocket. Broadcastwasa privileged 
operation in earlier versi onsof the system. With protocolsthat support out-of-Pand data, the so_oobinline option requests 
that out-of-Pand data Peplaced in thenormal data input queueasreceived; itwill then Pe accessi Pie with recv or read calls 
without the msgjmb flag. Some protocols always Pehave as if this option is set. 

so_sndbuf and so_rcvbuf areoptionsto adjust thenormal Puffer sizesallocated for output and input Puffers, respectivdy. The 
Puffer sizemay Peincreased for high-volumeconnectionsor may Pedecreased to limit the possi Pie Packlog of incomi ng data. 
Thesystem placesan aPsolute limit on thesevalues. 

so_sndlowat isan option to set the minimum count for output operati ons. M ost output operati ons processali of the data 
supplied Py the cali, deli veri ng datato the protocol fortransmission and Plockingasnecessary forflow control. N onPIocking 
output operationswill process as much dataas permitted suPject to flow control without Plocking, Putwill process no data if 
flow control doesnot allow thesmaller of the low water mark valueortheentirerequest to Peprocessed. A seiect(2) 
operation testi ng the abi lity to writeto a socket will return trueonly if the low water mark amount could Peprocessed. The 
default value for so_sndlowat is set to aconvenient sizefor network efficiency, often 1024. 

so_rcvlowat isan option to set the minimum count for input operations. In general, reca ve calls will Plock until any 
(nonzero) amount of data isreceived, then return with thesmaller of the amount availaPle or the amount requested. The 
default value for so_rcvlowat is 1 . If so_rcvlowat isset to a larger value, Plocking recei ve calls normally wait until they have 
recaved the smaller of the low water mark value or the requested amount. Receive calls may stili return lessthan the low 
water mark if an errar occurs, asignal iscaught, orthetypeof data next in the receive queueisdifferent than that returned. 

so_sndtimeo is an option to set a ti me-out value for output operations. It accepts a s t r u c t timevai parameter with the 
numPer of seconds and microsecondsused to I i mi twaits for output operati ons to complete. If a send operation hasPlocked 
for this much ti me it returnswith a partial count or with the errar ewouldblock if no data were sent. In thecurrent 
implementation, thistimer isrestarted each ti me additi onal data are delivered to the protocol, implying that the limit applies 
to output portions ranging in sizefrom the low water mark to the high water mark for output. 

so_rcvtimeo isan option to set a ti me-out value for input operations. It accepts a s t r u c t timevai parameter with thenumPer 
of seconds and microsecondsused to limit waits for input operations to complete. In thecurrent implementation, thistimer 
isrestarted each timeadditional data are recei ved Py the protocol, and thus the limit isin effect an i nacti vi ty timer. If a 
reca ve operation hasPeen Plocked for this much ti me without reca vi ng addi ti onal data, it returnswith a short count or with 
the errar ewouldblock if no data were received. 

Finally, so_type and so_error are opti ons used only with setsockopt. 

so_type returns the typeof thesocket, sudi as sock_stream; it isuseful for serversthat inherit socketson startup. 

so_error returns any pendi ng errar on thesocket and clears the errar status. It may Peused to check for asynchronouserrors 
on connected datagram sockets or for other asynchronouserrors. 



RETURN VALUE 

On success, 0 is returned. On errar, -1 is returned and ermo isset appropriately. 



ERRORS 



EFAULT 



EBADF 



EN0TS0CK 



EN0PR0T00PT 



Thearguments isnotavalid descri ptor. 
Thearguments is a file, nota socket. 
Theoption isunknown atthelevd indicated. 

Theaddress pointed to Py optvai isnot in a valid part of the process address space. For 
getsockopt, thiserror may also Pe returned i f opti en isnot in a valid part of the process 
address space. 
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HISTORY 

These system calls appeared in BSD 4.2. 
BUGS 

Several of thesocket optionsshould behandled at lower levelsof the system 
SEEALSO 

ioctl(2), socket(2), getprotoent(3), protocols(5) 

gettimeof day, settimeof day 

gettimeof day, settimeof day— G et/ Set ti me 

SYNOPSIS 

#include <sys/time.h> 
#include <unistd.h> 

int gettimeofday(struct timeval *tv, struct timezone *t z ) ; 
int settimeofday(const struct timeval "tv , const struct timezone *tz); 

D ESC RIPTIO N 

gettimeof day and settimeof day Can Set the ti me as well as a timezone. t v ÌS a timeval struct, asspecified in /usr/include/ 
sys/time.h: 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 

>; 

and tz is a timezone: 

struct timezone { 

int tzjninuteswest; 

/* minutes west of Greenwich */ 

int tz_dsttime; 

/* type of dst correction */ 

}; 

with daylight savingstimesdefined asfollows: 

DST_NONE /* not on dst */ 



DSTJJSA 


/ * 


USA style dst */ 


DST_AUST 


/ * 


Australian style dst */ 


DST_WET 


/ * 


Western European dst */ 


DST_MET 


/ * 


Middle European dst */ 


DST_EET 


/ * 


Eastern European dst */ 


DST_CAN 


/ * 


Canada */ 


DST_GB 


/ * 


Great Britain and Eire */ 


DST_RUM 


/ * 


Rumania */ 


DST_TUR 


/ * 


Turkey */ 


DST_AUSTALT 


/ * 


Australian style with shift in 1986 */ 



BSD M an Page, 22 Aprii 1996 



getuid, geteuid 

And thefollowing macros are defined to operateon this: 

#define timerisset(tvp) \ 

( (tvp) ->tv_sec !! (tvp) ->tv_usec) 
#define timercmp(tvp, uvp, cmp)\ 

( (tvp) ->tv_sec cmp (uvp) ->tv_sec ||\ 

(tvp) ->tv_sec == (uvp) ->tv_sec &&\ 

(tvp) ->tv_usec cmp (uvp) ->tv_usec) 
#define timerclear(tvp) 

( (tvp) ->tv_sec = (tvp) ->tv_usec = 0) 

Ifeithertv or t z isnull, the corresponding structure is not set or returned. 
Only thesuperuser can use settimeofday. 

ERRO RS 

eperm settimeofday iscalled by someone other than thesuperuser. 

einval Timezone(orsomethingelse) isinvalid. 

C0NF0RMST0 

BSD 4.3 

SEEALSO 

date(l), adjtimex(2), time(2), ctime(3), ftime(3) 

Linux 1.2.4, 15 Aprii 1995 

getuid, geteuid 

getuid, geteuid— G et user identity 
SYNOPSIS 

#include <unistd.h> 
uid_t getuid(void) ; 
uid_t geteuid(void) ; 

DESCRIVO N 

getuid returnsthe real user ID of thecurrent process. 
geteuid returnstheeffectiveuser ID of thecurrent process. 

Thereal ID correspondsto thelD of the cai li ng process. T he effective I D correspondsto theset ID bitonthefilebeing 
executed. 

ERRORS 

These functions are always successful . 
C0NF0RMST0 

POSIX, BSD 4.3 

SEEALSO 

setreuid(2), setuid(2) 

Linux 0.99.11, 23 July 1993 
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idle 

idie— M akes processo idle 
SYNOPSIS 

#include <unistd.h> 
void idle(void) ; 

D ESC RIPTIO N 

idie isan internai system cali used during bootstrap. It markstheprocess's pagesasswappable, lowers its priority, and enters 
themain scheduling loop, idie never returns. 

Only processo may cali idle. Any user process, even a processwith superuser permission, will receiveEPERM. 
RETURN VALUE 

idie never returnsfor processo, and al ways returns -1 fora user process. 
ERRORS 

eperm A Iways, for a user process 

Linux 1.1.46, 21 August 1994 

ioctl 

iocti— Controls devi ces 
SYNOPSIS 

#include <sys/ioctl.h> 

int ioctl(int d .intrequest , ...); 

(The "third" argument i straditi onally char *a r g p and will beso named forthisdiscussion.) 
DESCRIPTION 

The iocti function manipulates theunderlying device parametersof special files. In parti cular, many operating characteris- 
ticsof character special files (for example, termi nals) may be controlied with iocti requests. The argument d must bean open 
fi le descri ptor. 

An iocti request has encoded in it whether the argument is an i n parameterorout parameter, and the sizeof the argument 
a r g p in bytes. M acrosand definesused in specifyingan iocti request arelocated in the f i le <s y s / i octi . h>. 

RETURN VALUE 

On success, e isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

ebadf d is nota valid descri ptor. 

enotty d is not associateci with a character special device. 

enotty Thespecified request does not applyto the kind of object that thedescri ptor d references. 

EINVAL request Orargp isnotvalid. 

HI STORY 

An iocti function cali appeared in version 7 AT&T UNIX. 




SEEALSO 

execve(2), fcntl(2), mt(4), sd(4), tty(4) 

INTRODUCTION 

Thisisiocti List 1.3.27, a list of iocti cai Is i n Linux/i386 kernel 1.3.27. It contai ns 421 ioctisfrom /usr/inciude/ 
fasm,iìnuxg/*.h. For each iocti, you'll find thenumerical value, name, and argument type. 

An argumenttypeof const struct foo * meanstheargumentisinputto thekernel. struct too * means the kernel outputs 
the argument. If thekernel uses the argument for both input and output, thisismarked with // i-o. 

Some ioctistake more arguments or return morevaluesthan a single structure. Thesearemarked // more and aredocu- 
mented further in a separate section. 

This list is incomplete. 1 1 does not include 

■ ioctis defi ned internai to thekernel (scsi iocti. h). 

■ ioctis defined in modules distributed separately from the kernel. 

And, of course, I may haveerrorsand omissions. 

Please e-mail changesand commentsto mecwuracef.shout.net. I am particularly interested in loadable modules that define 
their own ioctis. If you know of such a module teli mewherel can ftp it, and HI include its ioctis in my next release. 

MAIN TABLE 



<i nel aiti as m- i 3 8 6/ socket . h> 



0x00008901 


FIOSETOWN 


const int * 


0x00008902 


SIOCSPGRP 


const int * 


0X00008903 


FIOGETOWN 


int * 


0X00008904 


SIOCGPGRP 


int * 


0X00008905 


SIOCATMARK 


int * 


0X00008906 


SIOCGSTAMP 


timeval * 


ìcl udeyasm- i 386/termi os. h> 


0x00005401 


TCGETS 


struct termios * 


0x00005402 


TCSETS 


const struct termios * 


0x00005403 


TCSETSW 


const struct termios * 


0X00005404 


TCSETSF 


const struct termios * 


0X00005405 


TCGETA 


struct termio * 


0X00005406 


TCSETA 


const struct termio * 


0X00005407 


TCSETAW 


const struct termio * 


0X00005408 


TCSETAF 


const struct termio * 


0X00005409 


TCSBRK 


int 


0X0000540A 


TCXONC 


int 


0X0000540B 


TCFLSH 


int 


0X0000540C 


TIOCEXCL 


void 


0X0000540D 


TIOCNXCL 


void 


0X0000540E 


TIOCSCTTY 


int 


0X0000540F 


TIOCGPGRP 


pid_t * 


0X00005410 


TIOCSPGRP 


const pid_t * 
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<i nel j d e / asm- i 386 / termi os. h> 



0x00005411 


TIOCOUTQ 


int * 


0X00005412 


TIOCSTI 


const char * 


0x00005413 


TIOCGWINSZ 


const struct winsize * 


0X00005414 


TIOCSWINSZ 


struct winsize * 


0X00005415 


TIOCMGET 


int * 


0X00005416 


TIOCMBIS 


const int * 


0X00005417 


TIOCMBIC 


const int * 


0X00005418 


TIOCMSET 


const int * 


0X00005419 


TIOCGSOFTCAR 


int * 


0X0000541A 


TIOCSSOFTCAR 


const int * 


0X0000541 B 


FIONREAD 


int * 


0X0000541 B 


TIOCINQ 


int * 


0X0000541 C 


TIOCLINUX 


const char * 


0X0000541 D 


TIOCCONS 


void 


0X0000541 E 


TIOCGSERIAL 


struct serial_strucct * 


0X0000541 F 


TIOCSSERIAL 


const struct serial_strucct * 


0X00005420 


TIOCPKT 


const int * 


0X00005421 


FIONBIO 


const int * 


0X00005422 


TIOCNOTTY 


void 


0X00005423 


TIOCSETD 


const int * 


0X00005424 


TIOCGETD 


int * 


0X00005425 


TCSBRKP 


int 


0X00005426 


TIOCTTYGSTRUCT 


struct tty_strucct * 


0X00005450 


FIONCLEX 


void 


0X00005451 


FIOCLEX 


void 


0X00005452 


FIOASYNC 


const int * 


0X00005453 


TIOCSERCONFIG 


void 


0X00005454 


TIOCSERGWILD 


int * 


0X00005455 


TIOCSERSWILD 


const int * 


0X00005456 


TIOCGLCKTRMIOS 


struct termios * 


0X00005457 


TIOCSLCKTRMIOS 


const struct temios * 


0X00005458 


TIOCSERGSTRUCT 


struct async_strucct * 


0X00005459 


TIOCSERGETLSR 


int * 


0X0000545A 


TIOCSERGETMULTI 


struct serial_multiport_strucct * 


0X0000545B 


TIOCSERSETMULTI 


const struct serial_multiport_strucct * 


ic I atei I i n u x/ a x 2 5 . h > 


0X000089E0 


SI0CAX25GETUID 


const struct sockaddr_ax25 * 


0X000089E1 


SI0CAX25ADDUID 


const struct sockaddr_ax25 * 


0X000089E2 


SI0CAX25DELUID 


const struct sockaddr_ax25 * 


0X000089E3 


SI0CAX25N0UID 


const int * 




<i nel u d e / linux/ a x 2 5 . h> 



0X000089E4 


SI0CAX25DIGCTL 


const int * 


0X000089E5 


SI0CAX25GETPARMS 


struct ax25_parms_strucct * // 1-0 


0X000089E6 


SI0CAX25SETPARMS 


const struct ax25_parms-struct * 


<i nel u d e / 1 i n ux/ cdk h> 


0x00007314 


STL_BINTR 


void 


0x00007315 


STL_BSTART 


void 


0x00007316 


STL_BSTOP 


void 


0x00007317 


STL_BRESET 


void 


<i nel u d e / 1 i n u x / cdr om. h> 


0X00005301 


CDROMPAUSE 


void 


0x00005302 


CDROMRESUME 


void 


0x00005303 


CDROMPLAYMSF 


const struct cdrom_msf * 


0X00005304 


CDROMPLAYTRKIND 


const struct cdrom_ti * 


0X00005305 


CDROMREADTOCHDR 


struct cdrom_tochdr * 


0X00005306 


CDROMREADTOCENTRY 


struct cdrom_tocentry *// 1-0 


0x00005307 


CDROMSTOP 


void 


0x00005308 


CDROMSTART 


void 


0x00005309 


CDROMEJECT 


void 


0X0000530A 


CDROMVOLCTRL 


const struct cdrom_volctrl * 


0X0000530B 


CDROMSUBCHNL 


struct cdrom_subchnl * // 1-0 


0X0000530C 


CDR0MREADM0DE2 


const struct cdrom_msf * // MORE 


0X0000530D 


CDROMREADMODE1 


const struct cdrom_msf * // MORE 


0X0000530E 


CDROMREADAUDIO 


const struct cdrom_read_audio * 


0X0000530F 


CDROMEJECT 


SW int 


0X00005310 


CDROMMULTISESSION 


struct cdrom_multisession * // 1-0 


0x00005311 


CDROM_GET_UPC 


struct f char [8] ; g * 


0x00005312 


CDROMRESET 


void 


0x00005313 


CDROMVOLREAD 


struct cdrom_volctrl * 


0x00005314 


CDROMREADRAW 


const struct cdrom_msf * // MORE 


0x00005315 


CDROMREADCOOKED 


const struct cdrom_msf * // MORE 


0x00005316 


CDROMSEEK 


const struct cdromjnsf * 


<i nel u d e / 1 i n u x / c m2 0 6 . h> 


0x00002000 


CM206CTL_GET_STAT 


int 


0x00002001 


CM206CTL_GET_LAST_STAT 


int 
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<i nel u d e / 1 i n u x / c y c I ad es h > 



0X00435901 


CYGETMON 


struct cycladesjnonitor * 


0X00435902 


CYGETTHRESH 


int * 


0X00435903 


CYSETTHRESH 


int 


0X00435904 


CYGETDEFTHRESH 


int * 


0X00435905 


CYSETDEFTHRESH 


int 


0X00435906 


CYGETTIMEOUT 


int * 


0X00435907 


CYSETTIMEOUT 


int 


0X00435908 


CYGETDEFTIMEOUT 


int * 


0x00435909 


CYSETDEFTIMEOUT 


int 


iclude/linux/ext2 f s . h > 


0x80046601 


EXT2_I0C_GETFLAGS 


int * 


0x40046602 


EXT2_I0C_SETFLAGS 


const int * 


0x80047601 


EXT2_I0C_GETVERSI0N 


int * 


0x40047602 


EXT2_I0C_SETVERSI0N 


const int * 


icl u d e / 1 i nux/fd. h> 


0X00000000 


FDCLRPRM 


void 


0X00000001 


FDSETPRM 


const struct f loppy_struct * 


0x00000002 


FDDEFPRM 


const struct f loppy_struct * 


0x00000003 


FDGETPRM 


struct floppy_struct * 


0X00000004 


FDMSGON 


void 


0x00000005 


FDMSGOFF 


void 


0x00000006 


FDFMTBEG 


void 


0x00000007 


FDFMTTRK 


const struct format_descr * 


0x00000008 


FDFMTEND 


void 


0X0000000A 


FDSETEMSGTRESH 


int 


0X0000000B 


FDFLUSH 


void 


0X0000000C 


FDSETMAXERRS 


const struct f loppy_max_errors * 


0X0000000E 


FDGETMAXERRS 


struct f loppy_max_errors * 


0X00000010 


FDGETDRVTYP 


struct f char [16] ; g * 


0x00000014 


FDSETDRVPRM 


const struct f loppy_drive_params * 


0x00000015 


FDGETDRVPRM 


struct f loppy_drive_params * 


0x00000016 


FDGETDRVSTAT 


struct floppy_drive_struct * 


0x00000017 


FDPOLLDRVSTAT 


struct floppy_drive_struct * 


0x00000018 


FDRESET 


int 


0x00000019 


FDGETFDCSTAT 


struct f loppy_fdc_state * 


0x0000001 B 


FDWERRORCLR 


void 


0X0000001 C 


FDWERRORGET 


struct f loppy_write_errors * 


0x0000001 E 


FDRAWCMD 


struct f loppy_raw_cmd * // MORE // 1-0 


0x00000028 


FDTWADDLE 


void 




<i ne I y de/ 1 i n u x/ f s . h > 



0X00001 25D 


BLKROSET 


const int * 


0X00001 25E 


BLKROGET 


int * 


0X0000125F 


BLKRRPART 


void 


0x00001260 


BLKGETSIZE 


int * 


0x00001261 


BLKFLSBUF 


void 


0x00001262 


BLKRASET 


int 


0x00001263 


BLKRAGET 


int * 


0X00000001 


FIBMAP 


int * // 1-0 


0x00000002 


FIGETBSZ 


int * 


icl u d e / 1 i n u x / hdreg. h> 


0x00000301 


HDIO_GETGEO 


struct hd geometry * 


0x00000302 


HDIO_GET_UNMASKINTR 


int * 


0x00000304 


HDIO_GET_MULTCOUNT 


int * 


0X00000307 


HDIOJ3ET_IDENTITY 


struct hd driveid * 


0x00000308 


HDIO_GET_KEEPSETTINGS 


int * 


0x00000309 


HDIO_GET_CHIPSET 


int * 


0X0000030A 


HDIO_GET_NOWERR 


int * 


0X0000030B 


HDIO_GET_DMA 


int * 


0x0000031 F 


HDIO_DRIVE_CMD 


int * // 1-0 


0x00000321 


HDIO_SET_MULTCOUNT 


int 


0X00000322 


HDIO_SET_UNMASKINTR 


int 


0X00000323 


HDIO_SET_KEEPSETTINGS 


int 


0X00000324 


HDIO_SET_CHIPSET 


int 


0X00000325 


HDIO_SET_NOWERR 


int 


0X00000326 


HDIO_SET_DMA 


int 



<i nel ode/ 1 i n u x / i f eql , h> 



0X000089F0 


EQL_ENSLAVE 


struct ifreq 




// MORE 


// 


1-0 


0X000089F1 


EQL_EMANCIPATE 


struct ifreq 




// MORE 


// 


1-0 


0X000089F2 


EQLJ3ETSLAVECFG 


struct ifreq 


* 


// MORE 


// 


1-0 


0X000089F3 


EQL_SETSLAVECFG 


struct ifreq 


* 


// MORE 


// 


1-0 


0X000089F4 


EQLGETMASTRCFG 


struct ifreq 


* 


// MORE 


// 


1-0 


0X000089F5 


EQLSETMASTRCFG 


struct ifreq 


* 


// MORE 


// 


1-0 



<i nel u d e / 1 i n u x / i f pi i p. h> 



0X000089F0 



SIOCDEVPLIP 



struct ifreq * // 1-0 
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<i nel u d e / 1 i n u x / i f ppp. h> 



0X00005490 


PPPIOCGFLAGS 


int * 


0X00005491 


PPPIOCSFLAGS 


const int * 


0X00005492 


PPPIOCGASYNCMAP 


int * 


0X00005493 


PPPIOCSASYNCMAP 


const int * 


0X00005494 


PPPIOCGUNIT 


int * 


0X00005495 


PPPIOCSINPSIG 


const int * 


0x00005497 


PPPIOCSDEBUG 


const int * 


0X00005498 


PPPIOCGDEBUG 


int * 


0X00005499 


PPPIOCGSTAT 


struct ppp_stats * 


0X0000549A 


PPPIOCGTIME 


struct ppp_ddinfo * 


0X0000549B 


PPPIOCGXASYNCMAP 


struct f int [8] ; g * 


0X0000549C 


PPPIOCSXASYNCMAP 


const struct f int [8] ; 


0X0000549D 


PPPIOCSMRU 


const int * 


0X0000549E 


PPPIOCRASYNCMAP 


const int * 


0X0000549F 


PPPIOCSMAXCID 


const int * 



<i nel u d e / 1 i nux/i px h> 

0X000089E0 SIOCAIPXITFCRT const char * 

0X000089E1 SIOCAIPXPRISLT const char * 

0X000089E2 SIOCIPXCFGDATA struct ipx_conf ig_data * 



<i nel u d e / 1 i n u x / kd. h> 



0X00004B60 


GIO_FONT 


struct f char [8192] ; g * 


0X00004B61 


PIO_FONT 


const struct f char [8192]; g * 


0X00004B6B 


GIO_FONTX 


struct console_font_desc * // MORE 1-0 


0X00004B6C 


PIO_FONTX 


const struct console_f ont_desc * / /MORE 


0X00004B70 


GIO_CMAP 


struct f char [48] ; g * 


0X00004B71 


PIO_CMAP 


const struct f char [48]; g 


0X00004B2F 


KIOCSOUND 


int 


0X00004B30 


KDMKTONE 


int 


0X00004B31 


KDGETLED 


char * 


0X00004B32 


KDSETLED 


int 


0X00004B33 


KDGKBTYPE 


char * 


0X00004B34 


KDADDIO 


int // MORE 


0X00004B35 


KDDELIO 


int // MORE 


0X00004B36 


KDENABIO 


void // MORE 


0X00004B37 


KDDISABIO 


void // MORE 


0X00004B3A 


KDSETMODE 


int 


0X00004B3B 


KDGETMODE 


int * 


0X00004B3C 


KDMAPDISP 


void // MORE 



<i nel yde/ 1 i nux/kd. h> 



0X00004B3D 


KDUNMAPDISP 


void // MORE 


0X00004B40 


GIO_SCRNMAP 


struct f char [E_TABSZ]; g * 


0X00004B41 


PIO_SCRNMAP 


const struct f char [ E_TABSZ ] ; g * 


0X00004B69 


GICMJNISCRNMAP 


struct f short [E_TABSZ]; g * 


0X00004B6A 


PIOJJNISCRNMAP 


const struct f short [E_TABSZ]; g * 


0X00004B66 


GIO_UNIMAP 


struct unimapdesc * // MORE // 1-0 


0X00004B67 


PIO_UNIMAP 


const struct unimapdesc * // MORE 


0X00004B68 


PIO_UNIMAPCLR 


const struct unimapinit * 


0X00004B44 


KDGKBMODE 


int * 


0X00004B45 


KDSKBMODE 


int 


0X00004B62 


KDGKBMETA 


int * 


0X00004B63 


KDSKBMETA 


int 


0X00004B64 


KDGKBLED 


int * 


0X00004B65 


KDSKBLED 


int 


0X00004B46 


KDGKBENT 


struct kbentry * // 1-0 


0X00004B47 


KDSKBENT 


const struct kbentry * 


0X00004B48 


KDGKBSENT 


struct kbsentry * // 1-0 


0X00004B49 


KDSKBSENT 


const struct kbsentry * 


0X00004B4A 


KDGKBDIACR 


struct kbdiaers * 


0X00004B4B 


KDSKBDIACR 


const struct kbdiaers * 


0X00004B4C 


KDGETKEYCODE 


struct kbkeycode * // 1-0 


0X00004B4D 


KDSETKEYCODE 


const struct kbkeycode * 


0X00004B4E 


KDSIGACCEPT 


int 


<i nel u d e / 1 i n u x / 1 p. h> 


0X00000601 


LPCHAR 


int 


0x00000602 


LPTIME 


int 


0x00000604 


LPABORT 


int 


0x00000605 


LPSETIRQ 


int 


0x00000606 


LPGETIRQ 


int * 


0x00000608 


LPWAIT 


int 


0x00000609 


LPCAREFUL 


int 


0X0000060A 


LPABORTOPEN 


int 


0X0000060B 


LPGETSTATUS 


int * 


0X0000060C 


LPRESET 


void 


0X0000060D 


LPGETSTATS 


struct lp stats * 


<i nel u d e / 1 i n u x / mr o ut e h> 


0X000089E0 


SIOCGETVIFCNT 


struct sioc_vif_req * // 1-0 


0X000089E1 


SIOCGETSGCNT 


struct sioc_sg_req * // 1-0 




P art II: System Calls 



<i nel ude/l i riux / mti o. h> 



0X40086D01 
0x801 C6D02 
0X80046D03 
0X80206D04 
0X40206D05 


MTIOCTOP 

MTIOCGET 

MTIOCPOS 

MTIOCGETCONFIG 

MTIOCSETCONFIG 


const struct mtop * 
struct mtget * 
struct mtpos * 
struct mtconfiginfo * 
const struct mtconfiginfo * 


<i nel u d e / 1 i n u x / net r om. h> 


0X000089E0 
0X000089E1 
0X000089E2 
0X000089E3 


SIOCNRGETPARMS 
SIOCNRSETPARMS 
SIOCNRDECOBS 
SIOCNRRTCTL 


struct nr_parms_struct * // 1-0 
const struct nr_parms_struct * 
void 

const int * 


<i nel u d e / 1 i nux/ sbped. h> 


0x00009000 
0x00005382 


DDIOCSDBG 
CDROMAUDIOBUFSIZ 


const int * 

int 


<i nel ude/l i nux/ s c c h > 


0X00005470 
0X00005471 
0X00005472 
0X00005473 
0X00005474 


TIOCSCCINI 

TIOCCHANINI 

TIOCGKISS 

TIOCSKISS 

TIOCSCCSTAT 


void 

const struct sccjnodem * 
struct ioctl_command * // 1-0 
const struct ioctl_command * 
struct scc_stat * 


<i nel ude/l i nux/scsi . h> 


0X00005382 
0X00005383 
0X00005384 
0x00005385 


SCSI_IOCTL_GET_IDLUN 
SCS I_I OCTL_TAGG ED_ENABLE 
SCS I_I OCTL_TAGG E D_D I SAB LE 
SCSI_I0CTL_PR0BE_H0ST 


struct f int [2] ; g * 

void 

void 

const int * // MORE 


<i nel u d e / li nux/ smb f s . h > 


0x80027501 


SMB_IOC_GETMOUNTUID 


uid t * 


<i nel ude/l i nux/ socki OS . h > 


0X0000890B 
0X0000890C 
0x00008910 
0x0000891 1 
0x00008912 
0x00008913 
0x00008914 


SIOCADDRT 

SIOCDELRT 

SIOCGIFNAME 

SIOCSIFLINK 

SIOCGIFCONF 

SIOCGIFFLAGS 

SIOCSIFFLAGS 


const struct rtentry * // MORE 
const struct rtentry * // MORE 
char [] 
void 

struct ifconf * // MORE // 1-0 
struct ifreq * // 1-0 
const struct ifreq * 



iodi ^ 

<i nel ude/l i nux/sockios.h> 



0x00008915 


SIOCGIFADDR 


struct ifreq * // 1-0 


0x00008916 


SIOCSIFADDR 


const struct ifreq * 


0x00008917 


SIOCGIFDSTADDR 


struct ifreq * // 1-0 


0X00008918 


SIOCSIFDSTADDR 


const struct ifreq * 


0x00008919 


SIOCGIFBRDADDR 


struct ifreq * // 1-0 


0X0000891A 


SIOCSIFBRDADDR 


const struct ifreq * 


0X0000891B 


SIOCGIFNETMASK 


struct ifreq * // 1-0 


0X0000891C 


SIOCSIFNETMASK 


const struct ifreq * 


0X0000891D 


SIOCGIFMETRIC 


struct ifreq * // 1-0 


0x0000891 E 


SIOCSIFMETRIC 


const struct ifreq * 


0X0000891 F 


SIOCGIFMEM 


struct ifreq * // 1-0 


0X00008920 


SIOCSIFMEM 


const struct ifreq * 


0X00008921 


SIOCGIFMTU 


struct ifreq * // 1-0 


0X00008922 


SIOCSIFMTU 


const struct ifreq * 


0X00008923 


OLD SIOCGIFHWADDR 


struct ifreq * // 1-0 


0X00008924 


SIOCSIFHWADDR 


const struct ifreq * // MORE 


0X00008925 


SIOCGIFENCAP 


int * 


0X00008926 


SIOCSIFENCAP 


const int * 


0X00008927 


SIOCGIFHWADDR 


struct ifreq * // 1-0 


0x00008929 


SIOCGIFSLAVE 


void 


0X00008930 


SIOCSIFSLAVE 


void 


0X00008931 


SIOCADDMULTI 


const struct ifreq * 


0x00008932 


SIOCDELMULTI 


const struct ifreq * 


0x00008940 


SIOCADDRTOLD 


void 


0X00008941 


SIOCDELRTOLD 


void 


0X00008950 


SIOCDARP 


const struct arpreq * 


0X00008951 


SIOCGARP 


struct arpreq * // 1-0 


0X00008952 


SIOCSARP 


const struct arpreq * 


0X00008960 


SIOCDRARP 


const struct arpreq * 


0X00008961 


SIOCGRARP 


struct arpreq * // 1-0 


0X00008962 


SIOCSRARP 


const struct arpreq * 


0X00008970 


SIOCGIFMAP 


struct ifreq * // 1-0 


0X00008971 


SIOCSIFMAP 


const struct ifreq * 



<i nel ude/l i nux/ sourdcard. h > 



0x00005100 

0X00005101 

0XC08C5102 
0XC0045103 
0x80045104 
0x80045105 
0X40045106 



SNDCTL_SEQ_RESET 

SNDCTL_SEQ_SYNC 

SNDCTL_SYNTH_INFO 

SNDCTL_SEQ_CTRLRATE 

SNDCTL_SEQ_GETOUTCOUNT 

SNDCTL_SEQ_GETINCOUNT 

SNDCTL SEQ PERCMODE 



void 
void 

struct synth_info * // 1-0 

int * // 1-0 

int * 

int * 

void 
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nel ude/ I i nux/ soundeard. h> 



0X402851 07 


SNDCTL FM LOAD INSTR 


const struct sbi instrument 


0x400451 08 


SNDCTL SEQ TESTMIDI 


bUI lo L ± 1 1 L 


0x400451 09 


SNDCTL SEQ RESETSAMPLES 


const int * 


0x800451 0A 


SNDCTL SEQ NRSYNTHS 


int * 


0x800451 0B 


SNDCTL SEQ NRMIDIS 


int * 


0XC07451 0C 


SNDCTL MIDI INFO 


struct nidi info * / / I -0 


0X400451 0D 


SNDCTL SEQ THRESHOLD 


bUII J L -LI 1 L 


0x000451 0F 


SNDCTI SYNTH MFMAVI 

OmUU IL u 1 N 1 n IvlLlvIMV L 


int * / / I -0 


0Y400451 0F 


SNDrTI FM 40P FNARI F 

OHuU 1 L [IVI tur LHnDLL 


mnet i nt * 

bUI 13 L -LI 1 L 


0XCFB851 1 0 


SNDCTL PMGR ACCESS 


^trurt nfltmnr infn * // T-fl 

OLI UU L [J a L IN y 1 XIIIU // 1 U 


0x000051 1 1 


SNDCTL SEQ PANIC 




0X400851 1 2 


SNDCTL SEQ OUTOFBAND 


bUI lo L J L 1 LI U L OCLj CVCIIL 1 C b 


0XC0045401 


SNDCTL TMR TIMEBASE 


int * // 1-0 


0X00005402 


SNDCTL TMR START 


void 


0x0000540*3 


SNDCTL TMR STOP 




0X00005404 


SNDCTL TMR CONTINUE 


void 


0XC0045405 


SNDCTL TMR TEMPO 


int * // 1-0 


0XC0045406 


SNDCTL TMR SOURCE 


int * / / I -0 


Pi Y 40014.^4.07 

W A t TlU*£J t T\J t TVJ f 


SNDCTI TMR MFTRDNDMF 

ONUu 1 l_ 1 Ivi n IvIL 1 nUNUIvlL 


IjUI lo L ± 1 1 l 


0X4004540R 


SNDCTI TMR SFI FCT 

ONUu 1 l_ 1 Ivi n OL LLu 1 


int * / / I -0 


0XPFRR5001 


SNDCTI PMfìR TFACF 
onuu i i_ riviun i rnuL 


oli uul \ja Liny i xiiiu // i yj 


0yP004fìn00 

WAOI0i£J t TUI_'IJi£/ 


SNDrTI MTDT PRFTTMF 
onuu i l ivi i u i r n l i ± ivi l 


int * / / I -0 


0xH004fìD01 


SNDCTL MIDI MPUMODE 


bUI IO L -LI 1 L 


0XC0216D02 


SNDCTL MIDI MPUCMD 


struct mpu cominand ree * / / 


0x00005000 


SNDCTL DSP RESET 




0X00005001 


SNDCTL DSP SYNC 


void 


0XC0045002 


SNDCTL DSP SPEED 


int * // 1-0 


0xC004500"ì 


SNDCTL DSP STEREO 


int * / / I -0 


0XC0045004 


SNDCTL DSP GETBLKSIZE 


int * // 1-0 


0xC004500fi 


SOUND PCM WRITE CHANNELS 


int * / / I -0 


0XP0045007 


SOUND PPM WRTTF FTI TFR 
Ouunu r vivi yvni il r i l i l n 


int * / / I -0 


0x0)000^008 


SNDCTI DSP POST 
jnuu i i_ uor ruo i 




0XP004500Q 


SNDCTI DSP SURDTVTnF 

ORUw l_ UOr OUDUlViUL 


int * / / I -0 


OxrOOd^iOOA 


SNDCTI DSP SFTFRARMFNT 

ONuu 1 l_ UOr OL 1 r nr\U,lvlLl *J 1 


int * / / I -0 


0X8004500B 


SNDCTL_DSP_GETFMTS 


int * 


0XC0045005 


SNDCTL_DSP_SETFMT 


int * // 1-0 


0X800C500C 


SNDCTL_DSP_GETOSPACE 


struct audio-buf -info * 


0X800C500D 


SNDCTL_DSP_GETISPACE 


struct audio-buf -info * 


0X0000500E 


SNDCTL_DSP_NONBLOCK 


void 


0X80045002 


SOUND_PCM_READ RATE 


int * 


0x80045006 


SOUND_PCM_READ CHANNELS 


int * 


0X80045005 


SOUND PCM_READ BITS 


int * 



iodi 



0X80045007 
0X00004300 
0XCFB04301 
0XC01 44302 
0XC01 44303 
0X40144304 
0X40144305 
0XC01 44306 
0XC01 44307 
0X4FA44308 
0X8FA44309 
0X80044D00 
0X80044D01 
0X80044D02 
0X80044D03 
0X80044D04 
0X80044D05 
0X80044D06 
0X80044D07 
0X80044D08 
0X80044D09 
0X80044D0A 
0X80044D0B 
0X80044D0C 
0X80044D0D 
0X80044D0E 
0X80044D0F 
0X80044D10 
0X80044D1C 
0X80044D1D 
0X80044D1E 
0X80044DFF 
0X80044DFE 
0X80044DFD 
0X80044DFB 
0X80044DFC 
0XC0044D00 
0XC0044D01 
0XC0044D02 
0XC0044D03 
0XC0044D04 
0XC0044D05 



SOUND_PCM_READ FILTER 

SNDCTL_COPR_RESET 

SNDCTL_COPR_LOAD 

SNDCTL_COPR_RDATA 

SNDCTL_COPR_RCODE 

SNDCTL_COPR_WDATA 

SNDCTL_COPR_WCODE 

SNDCTL_COPR_RUN 

SNDCTL_COPR_HALT 

SNDCTL_COPR_SENDMSG 

SNDCTL_COPR_RCVMSG 

SOUND_MIXER_READ_VOLUME 

SOUND_MIXER_READ_BASS 

SOUND_MIXER_READ_TREBLE 

SOUND_MIXER_READ_SYNTH 

SOUND_MIXER_READ_PCM 

SOUND_MIXER_READ_SPEAKER 

SOUND_MIXER_READ_LINE 

SOUND_MIXER_READ_MIC 

SOUND_MIXER_READ_CD 

SOUND_MIXER_READ_IMIX 

SOUND_MIXER_READ_ALTPCM 

SOUND_MIXER_READ_RECLEV 

SOUND_MIXER_READ_IGAIN 

SOUND_MIXER_READ_OGAIN 

SOUND _MIXER_READ_LINE1 

SOUND_MIXER_READ_LINE2 

SOUND JIXER_READ_LINE3 

SOUND_MIXER_READ_MUTE 

SOUND_MIXER_READ_ENHANCE 

SOUND MIXER_READ_LOUD 

SOUND _MIXER_READ_RECSRC 

SOUND_MIXER_READ_DEVMASK 

SOUND_MIXER_READ_RECMASK 

SOUND JIXER_READ_STEREODEVS 

SOUND MIXER_READ_CAPS 

SOUND_MIXER_WRITE_VOLUME 

SOUND_M IXER_WR I TE_BASS 

SOUND_MIXER_WRITE_TREBLE 

SOUND_MIXER_WRITE_SYNTH 

SOUND_MIXER_WRITE_PCM 

SOUND MIXER WRITE SPEAKER 



int * 
void 

const struct copr_buffer * 

struct copr_debug_buf * // 1-0 

struct copr_debug_buf * // 1-0 

const struct copr_debug_buf * 

const struct copr_debug_buf * 

struct copr_debug_buf * // 1-0 

struct copr_debug_buf * // 1-0 

const struct coprjnsg * 

struct coprjnsg * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * 

int * // 1-0 
int * // 1-0 
int * // 1-0 
int * // 1-0 
int * // 1-0 
int * // 1-0 
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<i nel ude/l i nux/soundeard. h> 



0XC0044D06 


SOUND_MIXER_WRITEJ_INE 


int * 


// 1-0 


0XC0044D07 


SOUND_MIXER_WRITE_MIC 


int * 


// 1-0 


0XC0044D08 


SOUND_MIXER_WRITE_CD 


int * 


// 1-0 


0XC0044D09 


SOUND_MIXER_WRITE_IMIX 


int * 


// 1-0 


0XC0044D0A 


SOUND _M IXER_WR I TE_ALTPCM 


int * 


// 1-0 


0XC0044D0B 


SOUND_MIXER_WRITE_RECLEV 


int * 


// 1-0 


0XC0044D0C 


SOUND_MIXER_WRITE_IGAIN 


int * 


// 1-0 


0XC0044D0D 


SOUND_MIXER_WRITE_OGAIN 


int * 


// 1-0 


0XC0044D0E 


SOUND_MIXER_WRITE_LINE1 


int * 


// 1-0 


0XC0044D0F 


S0UND_MIXER_WRITE_LINE2 


int * 


// 1-0 


0XC0044D10 


S0UND__MIXER_WRITE_LINE3 


int * 


// 1-0 


0XC0044D1C 


SOUND_MIXER_WRITE_MUTE 


int * 


// 1-0 


0XC0044D1D 


SOUND_MIXER_WRITE_ENHANCE 


int * 


// 1-0 


0XC0044D1E 


SOUND_MIXER_WRITE_LOUD 


int * 


// 1-0 


0XC0044DFF 


SOUND JIXER_WRITE_RECSRC 


int * 


// 1-0 


ci jde/ 1 i iilix / jmsdos f s . h > 


0X000004D2 


UMSDOS_READDIR_DOS 


struct 


umsdos_ioctl * // I -0 


0X000004D3 


UMSDOS_UNLINK_DOS 


const 


struct umsdos_ioctl * 


0X000004D4 


UMSDOS_RMDIR_DOS 


const 


struct umsdos_ioctl * 


0X000004D5 


UMSDOS_STAT_DOS 


struct 


umsdos_ioctl * // I -0 


0X000004D6 


UMSDOS_CREAT_EMD 


const 


struct umsdos_ioctl * 


0X000004D7 


UMSDOSJJNLINK_EMD 


const 


struct umsdos_ioctl * 


0X000004D8 


UMSDOS_READDI R_EMD 


struct 


umsdos_ioctl * // I -0 


0X000004D9 


UMSDOSJ3ETVERSION 


struct 


umsdos_ioctl * 


0X000004DA 


UMSDOS_INIT_EMD 


void 




0X000004DB 


UMSDOS_DOS_SETUP 


const 


struct umsdos_ioctl * 


0X000004DC 


UMSDOS_RENAME_DOS 


const 


struct umsdos_ioctl * 


ci u d e / 1 i nux/vt. h> 


0x00005600 


VT_OPENQRY 


int * 




0x00005601 


VT_GETMODE 


struct 


vtjnode * 


0x00005602 


VT_SETMODE 


const 


struct vtjnode * 


0x00005603 


VT_GETSTATE 


struct 


vt_stat * 


0x00005604 


VT_SENDSIG 


void 




0X00005605 


VT_RELDISP 


int 




0x00005606 


VT_ACT IVATE 


int 




0X00005607 


VT_WAI TACTI VE 


int 




0X00005608 


VT_DISALLOCATE 


int 




0X00005609 


VT_RESIZE 


const 


struct vt_sizes * 


0X0000560A 


VT_RESIZEX 


const 


struct vt_consize * 



iodi 



MORE ARGUMENTS 

Some ioctistake a pointer to astructurethat contai ns additi onal pointers. Thesearedocumented herein alphabetical order. 
cdromreadaudio takes an input pointer const struct cdrom read audio *. T he buf field points to an output buffer of length 

nframes * CD FRAMESIZE RAW. 

CDROMREADCOOKED, CDROMREADMODE1, CDR0MREADM0DE2, and CDROM-READRAW takean input pointer const struct cdrom msf *.They 

use the same pointer asan output pointerto char n. The length variesby request. For cdromreadmodei , most driversuse 
cd_framesize, but the optics Storage driver uses opt blocksize instead (both have the numeri cai value2048). 

CDROMREADCOOKED char [CD_FRAMESIZE] 

CDROMREADMODEI char [CD_FRAMESIZE or OPT_BLOCKSIZE] 

CDROMREADMODE2 char [CD_FRAMESIZE_RAW0] 

CDROMREADRAW char [ CD_FRAMESIZE_RAW] 

EQL_ENSLAVE, EQL_EMANCIPATE, EQL_GETSLAVECFG, EQL_SETSLAVECFG, EQL_GETMASTERCFG, and EQ L_SETMAST E R C FG take a Struct 

itreq *.Thetfr data field isa pointer to another structure asfollows: 

EQL_ENSLAVE const struct slaving_request * 

EQLEMANCIPATE const struct slaving_request * 

EQL_GETSLAVECFG struct slave^config * // I -0 

EQL_SETSLAVECFG const struct slave_config * 

EQL_GETMASTERCFG struct master_conf ig * 

EQLSETMASTERCFG const struct master_conf ìg * 

fdrawcmd takes a struct floppy raw cmd *. If fiags & fd raw write is nonzero, then data points to an i nput buffer of length 

length. Ifflags & FD RAW READ ÌS nonzero, then data pointstoan Output buffer Of length length. 

GIOFONTX and PI0_F0NTX take a struct console font desc * Ora const struct console_f ont_desc », respectively. chardata 

pointsto a buffer of char [charcount]. This is an output buffer forGio_FONTx and an input buffer for pio_fontx. 

GIOJJNIMAP and PIOJJNIMAP take a struct unimapdesc * ora const struct unimapdesc *, respectively. entries pointsto a 

buffer of struct unipair [entry et ]. This is an output buffer for giojjnimap and an input buffer for pi ojjnimap. 
kdaddio, kddelio, kddisabio, and kdenabio enableor disableaccessto I/O porta They are essenti al ly alternate i nterfaces to 

ioperm. 

kdmapdisp and kdunmapdisp enableor disablememory mappingsor I/O port access. They are noti mplemented in the kernel. 

scsi_ioctl_probe_host takes an input pointer const mt *, which isa length. It uses the same pointer asan output pointerto 
a char [] buffer of this length. 

siocaddrt and siocdelrt takean input pointer whosetypedependson the protocol: 

M OSt protOCOlS const struct rtentry * 

AX.25 const struct ax25_route * 

NET/ROM const struct nr_route_struct * 

siocgifconf takes a struct ifconf *.Theifc buf field pointsto a buffer of length ite ien bytes, into which the kernel writes 

a list Of type struct if req []. 

siocsifhwaddr takesan input pointer whosetypedependson theprotocol: 

M OSt protOCOlS const struct ifreq * 

AX.25 const char [AX25„ADDR_LEN] 

tioclinux takes a const char *. It usesthisto distinguish several independent subcases. In thefollowingtable, n + foo means 

foo after an N-bytepad. struct selection isimplicitly defined in drivers/char/selection.c: 
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TIOCLINUX 
TIOCLINUX 
TIOCLINUX 
TIOCLINUX 
TIOCLINUX 
TIOCLINUX 
TIOCLINUX 



1 + const struct selectìon * 

void 
void 

4 + const struct f long [8]; g 
char * 
char * 

1 + const char * 



DUPLICATE ÌOCtlS 

This list does not include ioctis in the range siocdevprivate and siocprotoprivate: 



0X00005382 
0X00005402 
0X00005403 
0X00005404 



FDSETPRM 
FDDEFPRM 

CDROMAUDIOBUFSIZ 
SNDCTL_TMR_START 
SNDCTL_TMR_STOP 
SNDCTL TMR CONTINUE 



FIBMAP 
FIGETBSZ 

SCSI_IOCTL_GET_IDLUN 

TCSETS 

TCSETSW 

TCSETSF 



Linux, 17 September 1995 



ioperm 

ioperm— Sets port i nput/ output permissions 
SYNOPSIS 

(finclude <unistd.h> 

int ioperm(unsigned long f r o m, unsigned long n u m, intt u r n_ on ) ; 

DESCRIPTION 

ioperm sets the port access permission bits for the process for n y m bytes starti ngfrom port address fra m to thevalueturn_on. 
T he use of ioperm requi res root privi leges. 

Only the first 0x3ff I/O portscan bespecified in thismanner. For more ports, theiopi function must beused. Permissions 
are not inherited on fork, but on exec they are This isuseful for givi ng port access permissions to nonprivi leged tasks. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and errno isset appropriately. 

CONFO RMSTO 

ioperm is Linux specific. 

SEEALSO 

iopi(2) 

Linux, 21 January 1993 



iopl 

iopi— C hanges I/O privi lege level 



ipc 




SYNOPSIS 

#include <unistd.h> 
int iopl(int I ève ) ; 

DESCRIPTION 

iopi changesthel/O privi legela/el of thecurrent process, asspecified ini evei . 

Thiscall isnecessaryto allow 8514-compatiPleX serversto run under Linux. BecausetheseX servers requ ire access to ali 
65536 I/O ports, the ioperm cali isnotsufficient. 

In additi on to granting unrestricted I/O port access, running at a higher I/O privi lege leve! also allows the process to disaPle 
interrupts. Thiswill proPaPly crash the system and isnot recommended. 

Thel/O privi lege I a/d foranormal processisO. 
RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

einval i evei is greater than 3. 

eperm Thecurrent user is not thesuperuser. 

NOTES FROM THE KERNEL SOURCE 

iopi hasto Peused when you want to access the I/O ports Peyond the 0x3ff range To get the full 65536 ports Pitmapped, 
you'd need 8KB of Pitmaps/ process, which isabit eccessive. 

SEE ALSO 

ioperm(2) 

Linux 0.99.11, 24 July 1993 



ipc 

ipc— System V IPC system calls 
SYNOPSIS 

int ipc(unsigned int cali, int first, int second, 
int t hi r d , void *pt r , long f i f t h ) ; 

DESCRIPTION 

ipc is a common kernel entry poi ntfor the System V IPC cai Is for messages, semaphores, and shared memory. cai 
determi nes which IPC function to invoke; theother arguments are passed through to the appropriate cali. 

User programsshould cali the appropri atefunctionsbytheir usuai names. 0 nly standard library implementorsand kernel 
hackers need to know about ipc. 

SEE ALSO 

msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2), semop(2), shmat(2), shmctl(2), shmdt(2), shmget(2) 

Linux 1.2.4, 15 Aprii 1995 
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kill 

kiii— Sends signal to a process 
SYNOPSIS 

«include <sys/types.h> 

«include <signal.h> 

int kill(pid t pi d ,ints i g ) ; 

DESCRIVO N 

The km system cali can beused to send any signal to any process group or process. 

If pi d i sposi ti ve, then signal si g issent to pi t. In thiscase, 0 isreturned on success and a negativevalueisreturned on errar. 

If pi d equals-1, then si g issent to every process except the first one, from higher numbersin theproc tableto lower. In this 
case, 0 isreturned on success, or the errar condition resulti ng from signal ing the last process isreturned. 

If pi d islessthan -1, then si g issent to every process in the process group -pi d. In thiscase, thenumber of processesthe 
signal wassent to isreturned and a negative value isreturned for fai Iure. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

einval An invai id signal issent. 

esrch Thepid or process group does not exist. N otethat an existing process mi ght bea zombie, a 

process that al ready committed termi nation, but hasnot yet been waitoed for. 

eperm TheeffectiveuserID of the process callingkiiio isnot equal to the effettive user I D of p i d , 

unlessthesuperuser called kmo. 

BUGS 

It isimpossibleto send a signal to task number one, themit process, forwhich it hasnot instali ed a signal handler. Thisis 
doneto ensure that the system isnot broughtdown accidentally. 

C0NF0RMST0 

SVID.AT&T, PO SIX.l, X/O PEN , BSD 4.3 

SEEALSO 

exit(2), exit(2), signal(2), signal(7) 

Linux, 1 N ovember 1995 

killpg 

kiiipg— Sends signal to a process group 
SYNOPSIS 

«include <signal.h> 

int killpg(int pgr p ,ints i g ) ; 

DESCRIPTION 

kiiipg sends the signal si g to the process group pgr p. Seesigaction(2) for a list of signals. I f p g r p i s 0, kiiipg sends the signal 
to the sendi ng process's process group. 




Thesending process and members of theprocess group must havethesameeffectiveuser ID, or thesender must bethe 
superuser. As a single special case, the continue signal sigcont may besent to any process that isadescendant of thecurrent 
process. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

einval si g isnotavalid signal number. 

esrch N o process can befound in the process group specified by pgr p. 

esrch The process group was gi ven as 0, but the sendi ng process does not have a process group. 

eperm Thesending process is not the superuser and oneor more of the target processeshasan 

effective user I D different from that of the sendi ng process. 

HI STORY 

Thekiiipg function cali appeared in BSD4.0. 
SEEALSO 

kill(2), getpgrp(2), signal(2) 

BSD Man Page 23 July 1993 



link 

link— M akesa new nameforafile 
SYNOPSIS 

#include <unistd.h> 

int link(const char "oldpath, const char *newpat h ) ; 

D ESC RIFTIO N 

link creates a new link (also known as a hard link) to an existing file. 
If newpath exists, itwill not be overwritten. 

Thisnew namemay beused exactly as the old onefor any operation; both names referto thesamefile(and so have the same 
permissionsand ownership) and it is impossibleto teli which name was the originai. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

exdev 0 1 d p a t h and newpath arenot on thesamefilesystem. 

eperm Thefilesystem containingoi dpat h and newpath does not support the creati on of hard links 

efault oidpath or newpat h points outside your accessible address space. 

eacces W rite access to the directory contai ni ng n e wp a t h is not allowed for the process's effective 

UID, or oneof the directories in oi dpat h or newpat h did not allow search (execute) 

permission. 

ENAMETOOLONG ol dpat h Or newpat h waStOO long. 

enoent A directory component in oi dpat h or newpat h does not exist or isa danglingsymbolic link. 

enotdir A component used as a directory in 0 dpat n or newpat n isnot, in fact, a directory. 
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ENOMEM 


1 nsuffi ci ent kernel memory wasavailable. 


EROFS 


Thefileison a read-only filesystem. 


EEXIST 


newpat h already exists. 


EMLINK 


Thefilereferred to by oi d p a t h already has the maximum number of links to it. 


ELOOP 


oi dpat h or newpat h containsa referenceto a circular symbolic link, that is, a symbolic link 




whoseexpansion containsa referenceto itself. 


ENOSPC 


T he device contai ni ng the fi le has no room forthenew directory entry. 


EPERM 


oi dpat h isthe . or . . entry of a directory. 



NOTES 

H ard links, ascreated by link, cannot span filesystems. Usesymiink if thisisrequired. 
C0NF0RMST0 

SVID.AT&T, POSIX, BSD 4.3 

BUGS 

On N FS fi le systems, the return codemay bewrong in case the N FS server performs the link creation and diesbeforeit can 
say so. Use stat(2) to find out if the link wascreated. 

SEEALSO 

symlink(2), unlink(2), rename(2), open(2), stat(2), ln(l), link(8) 

Linux, 17 August 1994 



listen 

ìisten— Listensfor connections on a socket 
SYNOPSIS 

#include <sys/socket.h> 

int listen(int_s ,int backlog); 

D ESC RIPTIO N 

To accept connections, a socket is first created with socket(2), avvi Ili ngnessto accept incomi ng connections and a queue 
limit for incoming connections are specified with ìisten, and then the connections are accepted with accept(2). The listen 
cali appliesonly to sockets of type sock_stream or sock_seqpacket. 

T he ba c k i o g parameter defines the maximum length the queue of pendi ng connections may grow to. If a connection request 
arriveswith the queue full, the eli ent might receivean errorwith an indication of econnrefused, or, if the underlying protocol 
supports retransmission, the request may beignored so that retri es may su cceed. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

ebadf Thearguments isnot a valid descriptor. 

enotsock Thearguments isnot a socket. 

eopnotsupp T he socket isnotof a type that supports the operati on ìisten. 



HI STORY 

T he ìisten function cali appeared in BSD 4.2. 




BUGS 

lf the socket isof typeaf_inet and thebackiog argument i s greater than 128, it is si lently truncated to 128. For portable 
applicati ons, don't rely on thisvalue sirice BSD (and at least some BSD -derived systems) I i mi t thebackiog to 5. 

SEEALSO 

accept(2), connect(2), socket(2) 

BSD Man Page, 23 J uly 1993 

llseek 

_iiseek— Repositionstheread/write file offset 
SYNOPSIS 

#include <unistd.h> 
#include <linux/unistd.h> 

_syscall5(int, llseek, uint, fd, ulong, hi, ulong, lo, lof f_t* , res, uint ,wh) ; 

int llseek(unsigned int fd, unsigned long offset.high, 

unsigned long of f set _ I ow ,loff_t * result , unsigned int whence); 

DESCRIVO N 

The_iiseekfunction repositions the offset of the file descripton d to ( of f set. hi gh«32) \ ottset^iow bytes relative to the 
beginning of the fi le thecurrent positi on in the fi le, or the end of the file, dependi ng on whether whence ìsseek_set, 
sEEK_cuR,or seek_end, respecti vely. 1 1 returns the resulti ng fi le position in the argument r e s u 1 1 . 

RETURN VALUES 

U pon successful completion,_iiseek returns 0. Otherwise, a valueof-1 isreturned and ermo is set to indicate the errar. 
ERRORS 

ebadf fd isnotan open file descriptor. 

EINVAL whence isinvalid. 

CONFO RMSTO 

Thisfunction is Linux speci fic. 

BUGS 

Thereisno support forfileswith a sizeof 2GB or more. 
SEEALSO 

lseek(2) 

Linux 1.2.9, 10Junel995 

lseek 

iseek— Repositions read/write file offset 
SYNOPSIS 

(finclude <unistd.h> 

off_t lseek (int f il des ,off_t offset ,int whence ) ; 
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D ESC RIPTIO N 

Theiseek function reposi ti ons the offset of the fi le descri ptor f i i d e s to theargument of f set accordi ng to the di recti ve 
whence. Theargument f i i des must bean open fi le descri ptor. iseek repositions the fi le pointer fi i d e s asfollows: 

If whence ìsseek_set, the offset is set to of f s et bytes. 

If whence ìsseek_cur, theoffset issetto itscurrent location plus of f set bytes. 

If whence ìsseek_end, theoffset issetto the size of the fi le plus of f s et bytes. 

Theiseek function allows the fi le offset to beset beyond the end of the exi sti ng end-of-file of the file. If data is later written 
atthispoint, subsequent readsof the data in the gap return bytes of zeros (unti I data isactually written into the gap). 

Some devi ces areincapableof seeking. The vai ue of the pointer associ ated with such a device isundefi ned. 
RETURN VALUES 

Upon successful completion, iseek returnstheresulting offset location asmeasured in bytes from thebeginning of the fi le. 
Otherwise, avalueof -1 isreturned and ermo issetto indicate the errar. 

ERRORS 

ebadf f m des is not an open file descriptor. 

espipe f m des isassociated with a pipe socket, or FIFO. 

einval whence is not a proper value. 

C0NF0RMST0 

POSIX, BSD 4.3 

BUGS 

Thisdocument'suseof whence is incorrect English, but maintained for historical reasons. 
SEEALSO 

dup(2), open(2), fseek(3) 

Linux 1.2.9, 10 Junel995 

mkdir 

mkdir— C reates a di rectory 
SYNOPSIS 

#include <sys/types.h> 
#include <fcntl.h> 
#include <unistd.h> 

int mkdir(const char *pat hname , mode_t mode); 

D ESC RIPTIO N 

mkdir attemptsto create a di rectory named pat hname. 

mode specifiesthepermissionsto use. It is modified by theprocess'sumask in the usuai way: the perm issi ons of the created 

file ÌS (mode & "umask) . 

T he newly created directory will beowned by the effecti ve U I D of theprocess. Ifthedi rectory containing the filehas the set 
group ID bit set, or if thefilesystem ismounted with BSD group semantics, thenew directory will inherit thegroup 
ownership from itsparent; otherwise, itwill beowned by the effecti ve G I D of the process. 

If the parent directory hastheset group ID bit set, so will the newly created directory. 



mknod 




RETURN VALUE 

mkdir returnsa on success, or -1 if an errar occurred (in which case, ermo isset appropriately). 
ERRORS 

EEXIST 
EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
ENOMEM 
EROFS 
ELOOP 

ENOSPC 
ENOSPC 

BUGS 

In someolder versi onsof Linux (for example, 0.99pl7) ali thenormal filesystemssometimeallow thecreation oftwo filesin 
the same directory with thesamename. Thisoccursonly rarely and only on a heavily loaded system. It isbelieved thatthis 
bug wasfixed in the M inixfilesystem in Li nux 0.99pl8 prerelease; and it ishoped that it wasfixed in theother filesystems 
shortly afterward. 

T nere are many i nf el i citi es in the protocol underlying N FS. 
SEEALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), open(2), mknod(2), stat(2), umask(2), mount(2), socket(2), socket(2), fopen(3) 

Linux 1.0, 29 M ardi 1994 

mknod 

mknod— C reates a di rectory 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <unistd.h> 

int mknodfconst char * p a t h n a me , mode_t mode,dev_t dev); 

DESCRIPTION 

mknod attemptsto createafilesystem node (fi le, device special file, or named pipe) named p a t h n a me , specified by mode and de», 
mode specifies both thepermissionsto use and thetypeof nodeto becreated. 

It should bea combinati on (usi ng bitwiseoR) of oneof the file types listed below and the pernii ssions for the new node. 
Thepermissionsaremodified by theprocess'sumask in the usuai way: Thepermissionsof thecreated node is (mode & 

"umask) . 



pat hna me al ready exists (not necessarily as a directory). 

pat hna me pointsoutsideyour accessi bleaddress space. 

Theparent di rectory does not allow write pernii ssion to theprocess, or oneof the 

directories in pat hname did not allow search (execute) permission. 

pat hna me wastOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 
A component used as a di rectory in pat hname isnot, in fact, a di rectory. 
I nsuffi ci ent kernel memory wasavailable. 

pat hname refersto a fi le on aread-only filesystem and write access wasrequested. 

pat hname contai ns a referenceto a ci rcular symbolic link, that is, a symbolic link whose 

expansion contai ns a referenceto itself. 

The device contai ni ng pathnamehasno room for the new directory. 

Thenew directory cannot becreated because the user's disk quota isexhausted. 
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Thefiletypeshould beone of s_ifreg, s_ifchr, s_ifblk, or s_ififo to specify a normal fi le (whi eh will becreated empty), 
character special file, block special file, or FIFO (named pipe), respectively, or 0, which will create a normal file. 

If the file typeissjFCHR or s_ifblk, then dev speci fies the major and minor numbersof thenewly created devi ce special file 
otherwise, it isignored. 

Thenewly created nodewill beowned by theeffectiveU ID of theprocess. If the directory containing the node has the set 
group ID bit set, or if thefilesystem is mounted with BSD group semantics, thenew nodewill inherit thegroup ownership 
from itsparent directory; otherwise it will beowned by the effective G I D of the process. 

RETURN VALUE 

mknod returnse on success, or -1 if an errar occurred (in which case, ermo isset appropriately). 



ERRORS 



EINVAL 
EEXIST 
EFAULT 
EACCES 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

ENOMEM 

EROFS 

ELOOP 

ENOSPC 



mode requested creation of something other than a FIFO (named pipe), and the Caller isnot 
thesuperuser; also returned if thefilesystem containing pat hname doesnotsupportthetype 
of node requested. 

mode requested creation of something other than a normal file, device special fi le or FIFO . 
pat hname already exists. 

pat hname pointsoutsideyour accessi bleaddress space. 

Theparent di rectory does not allow writepermission to theprocess, or oneof the 

directories in pat hname did not allow search (execute) permission. 

pat hname wastOO long. 

A directory component in pat hname does not exist or isa dangling symbol ic link. 
A component used asa directory in pat hname isnot, in fact, a directory. 
Insufficient kernel memory wasavailable. 

pat hname refersto a fi le on aread-only filesystem and write access was requested. 
pat hname contai ns a referenceto acircular symbolic link, that is, a symbol ic link whose 
expansion contai ns a referenceto itself. 
Thedevicecontainingpathname hasno room forthenew node. 



BUGS 

In someolder versi onsof Linux (forexample, 0.99pl7) ali the normal filesystemssometimeallow thecreation oftwo filesin 
the same directory with thesamename. Thisoccursonly rarely and only on a heavily loaded system. It isbelieved thatthis 
bug wasfixed in the M i nix filesystem in Li nux 0.99pl8 prerelease; and it ishoped that it wasfixed in the other fi lesystems 
shortly afterward. 

mknod cannot beused to create directories or socket files, and cannot be used to create normal filesby users other than the 
superuser. 

T nere are many infelicities in the protocol underlying N FS. 
SEE ALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), open(2), mkdir(2), stat(2), umask(2), mount(2), socket(2), fopen(3) 

Linux 1.0, 29 M arch 1994 



mlock 

miock— D isables pagi ng for some parts of memory 



mlockall 



SYNOPSIS 



#include <sys/mman.h> 

int tnlock(const void *addr , size_t len); 



DESCRIPTION 



miock disables paging for thememory in the range starti ng at ad dr with length i en bytes. Ali pagesthat contai n a part of the 
specified memory range are guaranteed to beresident in RAM when themiock system cali returns successfully and they are 
guaranteed to stay in RAM until thepagesareunlocked again by muniockor muniockaii or unti I theprocessterminatesor 
starts another program with exec. Child processes do not inherit pagelocksacrossafork. 

M emory locking hastwo main applications: real-timealgorithmsand high-security data processing. Real-timeappl ications 
require deterministic timing, and, I i ke scheduli ng, paging isone major cause of unexpected program execution delays. Real- 
ti me applicati onswi II usually also switch to a real-time scheduler with sched setscheduier. 

C ryptographic security software often h and les criticai bytes such as passwordsor secret keysasdata structures. Asa result of 
paging, thesesecrets could betransferred onto a persi stent swap store medium, wherethey might be accessi bl e to theenemy 
long after the security software haserased the secrets in RAM and termi nated. 

M emory locksdo not stack, that is, pagesthat havebeen locked several timesby Calisto miock or miockaii will beunlocked 
by a single cali to muniockforthecorresponding range or by muniockaii. Pagesthat are mapped to several locati ons or by 
several processes stay locked into RAM as long asthey are locked at least at one location or by at least one process. 

On POSIX systems on which miock and muniock are avai lable, _posix_memlock_range isdefined in <umstd.h> and thevalue 
pagesize from <iimits.h> i ndicates the number of bytes per page. 



On success, miock returns a. 0 n errar, -1 isreturned, ermo isset appropriately, and no changesaremadeto any locksin the 
address space of the process 



RETURN VALUE 



ERRORS 



EINVAL 



ENOMEM 



EPERM 



Some of the specified address range does not correspond to mapped pagesin the address 
space of the process or the process tri ed to exceed the maximum number of allowed locked 
pages. 

T he cali i ng process does not have appropri ate privi leges. 0 nly root processes are al lowed to 
lock pages. 

en was not a positive number. 



STANDARD S 

POSIX.lb, SVR4 




Linux 1.3.43, 26 N ovember 1995 



mlockall 



miockaii— D isables paging for cai I i ng process 



SYNOPSIS 



#include <sys/mman.h> 
int mlockall(int f I ags ) ; 
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DESCRIPTION 

miockaii disables paging for ali pages mapped into the address space of the calling process. Thisincludesthepagesof the 
code, data and stack segments, shared librari es, user space kernel data, shared memory, and memory-mapped files. Ali 
mapped pages are guaranteed to beresident in RAM when themiockaii system cali returnssuccessfully and they are 
guaranteed to stay in RAM until the pages are unlocked again by muniockor muniockaii or unti I theprocessterminatesor 
starts another program with exec. Child processesdo not inherit pagelocksacrossafork. 

M emory locking hastwo main applications: real-time algorithms and high-security data processing. Real-timeappl ications 
require deterministic timing, and, I i ke scheduli ng, paging isone major cause of unexpected program execution delays. Real- 
ti me applicati onswi II usually also switch to a real-time scheduler with sched setscheduier. Cryptographic security software 
often handles criticai bytessuch aspasswordsor secret keysasdatastructures. Asa result of paging, thesesecretscould be 
transferred onto a persi stentswap store medium, wherethey might be accessi bleto theenemy long after the security software 
haserased thesecrets in RAM and termi nated. For security applications, only small partsof memory haveto belocked, for 
which miock isavailable. 

Thefi ags parametercan beconstructed from thelogical or of thefollowingconstants 

mcl_current Lock ali pages that are currently mapped into theaddress space of the process. 

mcl_future Lock ali pages that will becomemapped intotheaddressspaceoftheprocessinthefuture. 

Thesecould be, forinstance, new pages required byagrowingheap and stack aswell asnew 

memory mapped files or shared memory regions. 

If mcl_future has been specified and thenumber of locked pages exceeds the upper limit of allowed locked pages, the system 
cali that caused the new mapping will fail with enomem. If thesenew pages nave been mapped by the growing stack, the kernel 
will deny stack expansion and send asiGSEGv. 

Real-time processes should reserve enough locked stack pages before entering thetime-criti cai section, so no page fault can be 
caused by function calls. This can beachieved by calling a function that has a sufficiently large automati c vari able and that 
wri testo the memory occupied by this large array in order to touch these stack pages. Thisway, enough pages will be 
mapped for the stack and can belocked into RAM . The dummy writesensure that not even copy-on-write page faults can 
occur in the criticai section. 

M emory locksdo not stack, that is, pages that nave been locked several times by Calisto miockaii or miock will be unlocked 
by a single cali to muniockaii. Pages that are mapped to several locationsor by several processes stay locked into RAM as long 
asthey are locked at least at one location or by at least one process. 

On POSIX systems on which miockaii and muniockaii are available, posix memlock is defi ned in <unistd.n>. 
RETURN VALUE 

On success, miockaii returnsa. On errar, -1 isreturned and errno is set appropriately. 
ERRORS 

enomem The process tried to exceed the maximum numberof allowed locked pages. 

eperm T he calling process does not have appropriate privileges. Only root processes are allowed to 

lock pages. 

einval U nknown flags were specified. 

STANDARD S 

POSIX.lb, SVR4 

SEE ALSO 

munlockall(2), mlock(2), munlock(2) 
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mmap, munmap 

mmap, munmap— M ap orunmap filesor devices into memory 
SYNOPSIS 

#include <unistd.h> 
#include <sys/mman.h> 
#ifdef POSIX MAPPED FILES 

void * mmap (void *st ar t , size_t I engt h ,int p r o t ,int f I ags ,int f d ,off_t offset ) ; 

int munmapfvoid *start, size_t length); 

#endif 

DESCRIVO N 

Themmapfunction asksto map i engt h bytes starti ng at offset offset fram thefile {or other object) specified byf d into 
memory, preferably at address start . Thislatter address is a hint only, and isusually specified asa. Theactual place where 
the object ismapped isreturned by mmap.Theprot argument d esc ribes the desi red memory protection. It hasthefollowing 
bits: 

prot_exec Pages may be executed. 

prot_read Pages may beread. 

protjvrite P ages m ay be wri tten . 

Thef i ags parameter specifies the type of themapped object, mapping options, and whether modifications madeto the 
mapped copy of the page are private to the processor areto beshared with other references. It hasthefollowing bits: 

map_fixed Do notselect adifferent address than the one specified. If the specified address cannot be 

used, mmap will fail. If map_fixed is specified, start must bea multiple of the pagesize. Useof 
thisoption isdiscouraged. 

map_shared Sharethis mapping with ali other processesthat map this object. 

map_private C reate a private copy-on-wri te mappi ng. 

Thesethreeflagsaredescribed in POSIX. 4. Linux also knows about map_denywrite, map_executable, and map_anon<ymous). 

The munmap system cali deletes the mappi ngsfor the specified address range and causesfurther references to addresseswithin 
therangeto generate invalid memory references. 

RETURN VALUE 

On success, mmap return s a poi nter to themapped area. On error, map_failed <-i) isreturned and ermo is set ap propri atei y. 
On success, munmap returnso, and on fai Iure it returns-1 and sets ermo (probably to einval). 

ERRORS 

ebadf fd is not a valid filedescriptor (and map_anonymous was not set). 

eacces map_private was asked, but f d is not open for reading. 0 r map_shared was asked and 

prot_write i s set, f d is not open forwriting. 

einval start or i e n g t h , and offset aretoo large, or not aligned on a pagesize boundary. 

etxtbusy map_denywrite was set but the object specifi ed by f d isopen forwriting. 

eagain Thefile hasbeen locked, ortoo much memory hasbeen locked. 

enomem N o memory isavailable. 



C0NF0RMST0 

POSIX.4. 
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SEEALSO 

get P agesize(2), msync(2), shm„open(2), B. 0 . G al I m ei ster, POSI X.4, 0 'Reilly, pp. 128-129, 389-391. 

Linux 1.3.86, 12 Aprii 1996 

modif y_ldt 

modif y_ldt— G ets or sets ldt 

SYNOPSIS 

#include <linux/ldt.h> #include <linux/unistd.h> 

_syscall3( int, modif y_ldt, int, fune, void *, ptr, unsigned long, bytecount ) 
int modify_ldt(int fune, void *ptr, unsigned long bytecount); 

DESCRIPTION 

modif y_idt readsor writes the locai descri ptor table(idt) for a process. T he ldt is a per-process memory-management table 
used by the Ì386 processor. For moreinformation on this table, seean Intel 386 processor handbook. 

When f une is 0, modif y_idt readstheidt into thememory pointed to by pt r . Thenumber of bytesread is the smaller of 
bytecount and the actual sizeof theidt. 

When fune is 1 , modif y_idt modifies one ìdt entry, ptr pointsto a modi f y_i dt _ i dt_s structureand bytecount must equal the 
sizeof thisstructure. 

RETURN VALUE 

On success, modifyjdt returns either the actual number of bytesread (for reading) ore (for writing). On failure, modify_idt 
returns-1 and sets ermo. 

ERRORS 

enosys fune is neither a non. 

einval ptr iso, orfunc is 1 and by t ec ou nt is not equal to the size of the structure 

modi f yj dtj dt_s, orfunc isi and thenew ìdt entry has i Negai values. 
efault ptr points outside the address space. 

SEEALSO 

vm86(2) 

Linux 1.3.6, 22 July 1995 

get_kernel_syms, create_module, initjiodule, deletejnodule 

get_kernel_syms, create_module, init_module, delete_module— Loadable module Support 

SYNOPSIS 

#include <linux/module.h> 

int get_kernel_syms(struct kernel_sym *table); 

int create_module(char *module_name, unsigned long size); 



get_kernel_syms, create_module, i nit_module; ddete_module 



int init_module(char "modulename, char *code, unsigned codesize, 
struct mod_routines *routines, struct symbol_table *symtab); 

int delete_module(char *module_name) ; 

struct kernel_sym { 

unsigned long value; 
char name [ SYM_MAX_NAME ] ; 

}; 

struct mod_routines { 
int (*init) (void) ; 
void (*cleanup) (void) ; 

}; 

struct module_ref { 

struct module *module; 
struct module_ref *next; 

}; 

struct internal_symbol { 
void *addr; 
char *name; 

}; 

struct symbol_table { 

int size; /* total, including string table!!! */ 
int n_symbols; 
int n_refs; 

struct internal_symbol symbol[0]; 
struct module_ref ref[0]; 

}; 

DESCRIVO N 

These system callshavenot yet been included in any library, which meansthatthey haveto be called by the 
syscaii(_NR_function) mechanism. get_kernei_syms(tabie); hastwo uses: First, if tabie ìsnull, thiscall will only return the 
number of symbols, including module names, that are available. Thisnumber should beused to reserve memo ry for that 
many items of struct kernel sym. 

If tabie isnot null, this cali will copy ali kernel symbols and module names (and versi on info) from the kernel to the space 
pointedto bytabie. The entri es are ordered in moduleUFO order. Foreach modulean entry that describes the module will 
befollowed by entries descri bi ng the symbols exported by this module. 

N ote that for symbols that descri bea module, the value partof the structure will contai n the kernel addressof thestructure 
that descri bes the module 

The name part of the structure is the module name prepended with #, asin #my module. The symbol that describes a module 
will appear before the symbols defined by thismodule. 

Ahead of the kernel resident symbols, a module name symbol with the"dummy" name# will appear. Thisinformation can 
beused to build a table of module referenceswhen modulesarestacked (or layered). create_moduie(moduie_name, size); will 
allocate size bytesof kernel space for a module and also create the necessary kernel structures— called name— for the new 
module. Themodulewill now exist in kernel space, with the statusMOD_uNiNiTiAi_izED.init moduie(moduie_name, code, 
codesize, routines, symtab);. 

Thisistheactual "module loader" that will load the module named nameinto the kernel. The parameters code and codesize 
referto therelocated binary object module that is codesize byteslong. N ote that the first 4 byteswill beused asa reference 
counter in kernel space, updated by theMOD_iNc_usE_couNT and modj>ec_use_count macros. 
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Thefunctionsdescribed in routines wil I beused to start and stop the module. These poi nters should therefore contai n the 
addressesof theinit_moduieo and cieanup_moduie() functionsthat haveto bedefined forali loadablemodules. 

If a module wantsto export symbolsfor useby other modules, or if the module makes referencesto symbolsdefined by other 
modules, theparameter symtab hasto pointto a stru ctu re thatd esc ribes these. A null valuefor symtab meansthat no symbols 
areexported and no referencesto other modules are made. 

The symtab thatwi II becopied into the kernel consistsof a symbol table structure immediately followed by a string table, 
contai ni ng the namesof the symbolsdefined by the module. The sizeelement hasto i nclude the sizeof this string table as 
well. Special considerationsfollow. 

Then_symbois and n_refs elementstells how many symbols and how many modulereferencesareincluded in the symbol 
table structure. Immediately after these integers, thearray of symbol definitionsfollows. Thenameelement in each struct 
internai symbol should actually not bean ordì nary pointer, butinstead the offset of the corresponding string table entry 
relative to the start of the symbol table structure. 

When ali defined symbols havebeen listed, the symboi_tabie structure conti nueswith thearray of module references, as 
described bythestruct moduie_ref elements. Onlythemodulefield of these structures haveto be i nitialized. The module 
addressesthat wereobtained from a previousget_kernei_syms cali, for elements with names starti ngwith # should becopied 
tothisfidd. 

If the module could besuccessfully loaded, and if the cali to the module function initjnoduieo also succeeds, the status of 
themodulewill bechanged to modrunning. Otherwise, the kernel memory occupied by module wi II befreed. 

deiete_nioduie(moduie_name); should beused to unload a module. If the module reference count shows that the module is not 
active and if there are no referencesto this module from other modules, the module function cieanupjnoduieo wil I be 
called. If ali these steps succeed, the kernel memory occupied by the module and its structures wi 1 1 befreed. 

DIAGNOSTICS 

If there are any errors, these functionswi II return thevalue -1, and theglobal vari able ermo wi 1 1 contai n the errar number. A 
descri pti ve text wi 1 1 also bewritten on the console device. 

SEE ALSO 

insmod(l), rmmod(l), lsmod(l), ksyms(l) 

HI STORY 

T he module support was fi rst concei ved by Anonymous. 

Linux version by Bas Laarhoven (bas9vimec.ni), 0.99.14 version byjon Tombs(jon@gtex02. us.es), extended by Bjorn 

Ekwall (bj0rn@blox.se). 

BUGS 

N aah... 

Linux, 25 J anuary 1995 

mount, umount 

mount, umount— M ount and unmount fi lesystems. 
SYNOPSIS 

#include <sys/mount.h> 
#include <linux/fs.h> 

int mount(const char *specialfile, const char * dir , 

const char * fi I esystemtype, unsigned long rwflag , const void * data); 

int umount(const char *s pec i a I f i I e ) ; 

int umount(const char *dir); 



mount, umount 



DESCRIPTION 



mount attaches thefilesystem specified by speci ai f i i e (which isoften a de/ice name) to the directory specified by dir. 
umount removes the attachmentof thefilesystem specified by s peci ai f i i e or di r . 
Only thesuperuser may mount and unmountfilesystems. 

T he f i I esystemtype argument maytakeoneof thevalueslisted in /proc/filesystems (SUCh aSminix, ext2, msdos, proc, nfs, 
iso9660). 

Therwf i ag argument has the magic number bxcoed in the top 16 bits, and various mount flags (as defined in <nnux/fs.h>) in 
thelow order 16 bits: 

#define MS_RDONLY 1 /* mount read-only */ 

#define MS_NOSUID 2 /* ignore suid and sgid bits */ 

#define MS_NODEV 4 /* disallow access to device special files */ 

#define MS_NOEXEC 8 /* disallow program execution */ 

#define MS_SYNC 16 /* writes are synced at once */ 

#define MS_REMOUNT 32 /* alter flags of a mounted FS */ 

#define MS_MGCJ/AL 0XC0ED0000 

If the magic number is absent, then the last two arguments are not used. 
T he da t a argument isinterpreted bythedifferentfilesystems. 



Thefollowing errar valuesresult from filesystem typeindependent errors. Each fi I esystem type may haveitsown special 
errorsand itsown special behavior. See the kernel sourcecodefordetails. 



RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 



ERRORS 



ENOENT 



EMFILE 



ENXIO 



EACCES 



ENOTDIR 



ENOMEM 



EFAULT 



EPERM 



ENODEV 



EINVAL 



EBUSY 



ENAMETOOLONG 



ENOTBLK 



The user isnot thesuperuser. 

f i i esystemtype not configured in the kernel. 

speci ai f i i e isnot a block device (if a device was required). 

speci ai f i i e i s al ready mounted. Or it cannot beremounted read-only becauseit stili holds 
files open for writing. 0 r, it cannot be mounted on di r becausedi r is stili busy (it isthe 
working directory of some task, the mount pointof another device, has open files, and so 
on). 

speci ai f i i e had an invalid superblock. Or, aremountwasattempted, wh ilespeci ai fi i e 
wasnot al ready mounted on di r . 0 r, an umount was attempted, whiledi r wasnota mount 
point. 

0 ne of the pointer arguments poi nts outside the user address space. 

The kernel could not allocate a free pagete copy filenamesor data into. 

A pathnamewas longerthan maxpathlen. 

A pathnamewas empty or had a nonexistent component. 

T he second argument, oraprefixofthe first argument, isnot a directory. 

A component of a path was not searchable. 

Or, mounting a read-only filesystem was attempted without giving theMsjDONLY flag. 
Or, the block devicespeci aitile islocated on a fi I esystem mounted with theins_NODEv 
option. 

The major number of the block devicespeci ai ti i e isout of range. 
(In case no block device is required:) Tableof dummy devices is full . 
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CONFORMSTO 

Thesefunctionsarerather Linux specific. 

SEEALSO 

mount(8), umount(8) 

Linux 1.1.67, 28 N ovember 1994 



mprotect 

mprotect— C ontrols allowable accesses to a region of memory 
SYNOPSIS 

#include <sys/mman.h> 

int mprotect(caddr_t a d d r , size_t *l e n , int prot); 

DESCRIPTION 

mprotect controis how a section of memory can beaccessed. If an access is di sai lowed by the protection given it, the program 
receivesasiGSEGv. 

prot isabitwise-OR of thefollowing values: 
prot_none The memory cannot beaccessed at ali. 

prot_read The memory can be read. 

prot_write The memory can bewritten to. 

prot_exec The memory can contai n executing code. 

Thenew protection replacesany existing protection. For example, if the memory had previously been marked prot_read, and 
mprotect isthen called with pr ot prot_write, itwill no longer bereadable 

RETURN VALUE 

On success, mprotect returnsa. On error, -1 isreturned and ermo is set appropriately. 
ERRORS 

einval addr isnot a valid pointer. 

efault The memory cannot beaccessed. 

eacces Thememory cannot be given the specified access. This can happen, for example, ifyou 

mmap(2) a fi le to which you haveread-only access, then ask mprotect to mark it prot_write. 
enomem Internai kernel structurescould not beallocated. 

EXAMPLE 

#include <stdio.h> 

«include <stdlib.h> 
«include <errno.h> 
«include <sys/mman.h> 

int 

main(void) 
{ 

char *p; 
char c; 



mremap 




/* Allocate a buffer; it will nave the default 

protection of PROT_READ ] PROT_WRITE . */ 
p = malloc(1024) ; 
if (!p) { 

perror( "Couldn 1 1 malloc ( 1024) " ) ; 

exit(errno) ; 

} 

c = p[666]; /* Read; ok */ 

p[666] = 42; /* Write; ok */ 

/* Mark the buffer read-only. */ 
if (mprotect(p, 1024, PROT_READ) ) { 

perror("Couldn't mprotect"); 

exit(errno) ; 

} 

c = p[666]; /* Read; ok */ 

p[666] = 42; /* Write; program dies on SIGSEGV */ 

exit(0); 

} 

SEEALSO 

mmap(2) 

Linux 1.2, 23Junel995 



mremap 

mremap— Remaps a virtual memory address 
SYNOPSIS 

#include <unistd.h> 
#include <sys/mman.h> 

void * mremap(void * ol daddress , size_t oldsize , size_t newsize, unsigned long flags) 

DESCRIPTION 

mremap expands(or shrinks) an existing memory mapping, potenti ally moving it at the same ti me (controlied by thef i ags 
argument and the available virtual address space). 

oi d_ address is the old address of the vi rtual memory Plock thatyou want to expand (or shrink). N otethat oi d_ address hasto 
Pepagealigned. oi d si ze istheold size of the vi rtual memory block. new_s i ze istherequested size of the vi rtual memory 
block after the resize 

Thef i ags argument isa bitmap of flags. 

In Linux thememory isdivided into pages. A user processhasone or linear vi rtual memory segments. Each virtual memory 
segment hasoneor moremappingsto real memory pages (in the page tabi e). Each virtual memory segment has itsown 
protection (access rights), which maycauseasegmentation violation if thememory isaccessed incorrectly (forexample, 
writing to a read-only segment). Accessi ng virtual memory outsi de of the segments will also cause a segmentation violation. 

mremap uses the Linux page table schema mremap changes the mapping between virtual addressesand memory pages. Thiscan 
beused to implementavery efficient reaiioc. 
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FLAGS 

mremap_maymove I ndicates whether theoperation should fai I, or changes the vi rtual addressif the resi ze 

cannot be doneat the current vi rtual address. 

RETURN VALUE 

On success, mremap retums a pointer to thenew virtual memory area. On error, -1 is returned, and ermo isset appropriately. 
ERRORS 

einval An invai id argumentwasgiven. M ost likeiy oi d_ address wasnot page ali gned. 

efault Segmentation fault. Someaddressin therangeoi d_address to oi d_ a d d r e s s +oi d_si ze isan 

invai id virtual memory address forthisprocess. You can also get efault even if thereexist 
mappi ngs that cover the wholeaddress space requested, but those mappings are of different 
types. 

eagain T he memory segment islocked and cannot be rem apped. 

enomem T he memory area cannot beexpanded at the current virtual address, and theMREMAP_MAYMOVE 

flagisnotsetinfiags. Orthereisnotenough (virtual) memory available. 

SEE ALSO 

getpagesize(2), reaiioc(3), maiioc(3), brk(2), sbrk(2), mmap(2), your favorite 0 S text bookfor more information on paged 
memory. (M odern 0 perating Systems by Andrew S. Tannenbaum, Inside Linux by Randolf Bentson, The Design of theU N IX 
Operating System by M auricej. Bach.) 

Linux 1.3.87, 12 Aprii 1996 

msgctl 

msgcti— H andles message control operations 
SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int msgctl ( int msqid, int cmd , struct msqid_ds * b u f ); 
int cmd, struct msqid_ds *buf; 

D ESC RIPTIO N 

Thefunction performs the control operation specified bycmd on the message queuewith identifiermsq d. Legai valuesforcmd 
are 

ipc stat Copiesinfo from the message queue data structureinto thestructurepointed to by b u f . The 

user must haveread access privi legeson the message queue. 
ipc set Writesthevaluesof somemembersof themsqid ds structure pointed to bybuf tothe 

message queue data structure, updating also itsmsg_ctime member. Considered members 

from the USer-Supplied struct msqid ds pointed tO bybuf aremsg_perm.uid, msg_perm.gid, 
and msg_perm. mode /* only lowest 9-bits */ msg_qbytes. 

T he calling process effective user I D must be one among superuser, creator or owner of the 
message queue Only the superuser can raisethemsg_qbytes value beyond the system 
parameterMSGMNB. 

ipc_rmid Remove immediately the message queue and itsdata structuresawakening ali waiting reader 

and writer processes (with an error return and ermo setto eidrm). The calling process 
effective user ID must beone among superuser, creator or owner of the message queue. 



msgget 



RETURN VALUE 

If successful, the return valuewill beaiotherwise, the return valuewill be-1 with ermo indicating the errar. 
ERRORS 

For afailing return, errnowill be setto oneof the followi ng values: 

eaccess Theargumentcmd isequal to ipc_stat, but the calling processhasno read access permis- 

sions on the message queue ms q i d . 

efault Theargumentcmd hasvalueiPC_SET or ipc_stat, but theaddresspointed to by b u f isn't 

accessi bl e. 

eidrm Themessagequeuewasremoved. 

EINVAL Invalid valueforcmd Or msqi d . 

eperm Theargumentcmd hasvalueiPC_SETonpc_RMiD, but the calli ng processeffective user ID 

has insuffi cient privi legesto executethecommand. N otethat thisisalso the case of a 
nonsuperuser processtryingto increasethemsg_qbytes value beyond thevaluespecified by 
the system parameter msgmnb. 

NOTES 

TheiPC_iNFo, msg_stat, and msg_info control callsareused by theipcs(l) program to provide information on allocateci 
resources. In the future thesecan bemodified asneeded or moved to a proc file system interface. 

SEEALSO 

ipc(5), msgget(2), msgsnd(2), msgrcv(2) 

Linux 0.99.13, 1 Novemberl993 



msgget 

msgget— G ets a message queue iden tifi er 



SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int msgget ( key_t key,int msgflg ); 

DESCRIPTION 

Thefunction returns the message queue identifier associateci to the value of thekey argument. A new message queue is 
created i f k e y has value ipc_private or key isn't ipc_private, no existing message queue is associateci to key, and ipc_creat is 
asserted in ms gf i g (that is, ms gf i g &ipc_creat isn't 0). The presence in msgf 1 g of thefields ipc_creat and ipc_excl plays the 
samerole, with respect to the existenceof the message queue, as the presence of o_creat and o_excl in the mode argument of 
theop_en(2) system cali: That is, the msgget function failsif msgf 1 g assertsboth ipc_creat and ipc_excl and a message queue 
al ready existsforkey. 

U pon creati on, thelower 9 bitsof the argument msgf 1 g defi ne the access permissions(forowner, group, and others) to the 
message queue in the same format, and with thesamemeaning, as for the access permissions parameter in theopen(2) or 
creat(2) system calls (though the execute permissions are notused by the system). 

Furthermore, whilecreating, the system cali initializes the system message queue data structuremsqid ds asfollows: 
msgjerm.cuid and msg_perm.uid are set to the effecti ve user I D of the calling process. 
msgjerm.cgid and msg_perm.gid are set to the effecti ve group I D of the calling process. 
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Thelowest-order 9 bitsof msg_perm.mode are setto the lowest-order 9 bit of msgf i g. 

msgjnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime are Set tO 0. 

msg_ctime is setto thecurrent ti me 
msg_qbytes issetto thesystem li mit MSGMNB. 

If the messagequeue al ready exists, the access permissionsareverified, and a check ismadeto seewhether it ismarked for 
destruction. 

RETURN VALUE 

If successful, the return value will be the message quaje identifier (a positive integer), otherwise-1 with ermo indicatingthe 
error. 



ERRORS 



Forafailing return, errnowil 


I be setto oneof the followi ng values: 


EACCES 


A message queue exists for kej, but the calli ng processhasno access permissionsto the 




queue 


EEXIST 


A message queue exists for key and msgf i g wasasserting both ipc_creat and ipc_excl. 


EIDRM 


The message queue ismarked asto be removed. 


ENOENT 


No message queue exists for key andmsgfig wasn't asserting ipc_creat. 


ENOMEM 


A message queue has to be created but the system has not enough memory for the new data 




structure. 


ENOSPC 


A messagequeue h asto be created but thesystem limit for the maximum number of 




message queues (msgmni) would be exceeded. 



NOTES 

ipcprivate isn't aflagfidd, but a key j: type. If this special value isused for key, thesystem cali ignoreseverything but the 
lowest-order 9 bitsof msgf i g and createsa new message queue (on success). 

T he followi ng is a system limit on message queue resourcesaffecting a msgget cali: 

msgmni Systemwide maximum number of message queues; policy dependent. 

BUGS 

Useof ipc_private doesn't inhibit other processes the access to the allocateci messagequeue. 

Asforthefiles, there is currently no intrinsic way for aprocessto ensure exclusi ve access to a message queue. Asserting both 
ipc_creat and ipc_excl in msgf i g only ensures(on success) that a new message queue will be created; it doesn't imply 
exclusi ve access to the message queue. 

SEEALSO 

ftok(3), ipc(5), msgctl(2), msgsnd(2), msgrcv(2) 

Linux 0.99.13, 1 N ovember 1993 

msgop 

msgop— C ompletes message operations 
SYNOPSIS 



# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 




int msgsnd ( int ms q i d , struct msgbuf *msgp",int msgsz, int msgflg ); 

int msgrcv ( int msqid, struct msgbuf *ms g p , int ms g s z , long msgtyp, int msgflg ); 

D ESC RIFTIO N 

To send or receivea message, the cali ing process allocatela structurethat looks likethefollowing: 

struct msgbuf { 
long mtype; /* message type, must be > 0 */ 
char mtext[1]; /* message data */ 

}; 

but with an array mtext of size msgsz , a nonnegative integer value. Thestructure member mtype must haveastrictly positive 
integervaluethatcan beused by the receiving processfor message selection (seethesection about msgrcv). 

The cali ing processmust havewrite access permissionsto send and read access permissionsto receivea message on thequeue. 

The msgsnd system cali queues a copy of the message poi nted to by the ms g p argument on the message queuewhoseidentifier 
isspecified by the value of the ms q i t argument. 

T he argument msgfi g speci fi es the system cali behavior if queuing thenew message wi II require morethan msg_qbytes in the 
queue Asserti ng ipc_nowait, the message wi II not besent and the system cali fails, returni ng with ermo setto eagain. 
Otherwisetheprocess issuspended until thecondition for the suspensi on no longer exists (in which case the message issent 
and the system cali succeeds), or the queue isremoved (in which case the system cali fails with ermo setto eidrm), or the 
processreceivesasignal that hasto becaught (in which case the system cali fails with ermo setto eintr). 

Upon successful completion, the message queue data structureisupdated asfollows: 
msg_ispid Set to the process D of the calling process. 

msg_qnum I ncremented by 1. 

msg_stime Set to the current ti me. 

Thesystem cali msgrcv reads a message from the message queue specified by ms q d into the msgbuf pointed to bythemsgp 
argument, removingfrom thequeue, on success, the read message. 

The argument msgsz specifies the maximum size in bytes for the member mtext of thestructure pointed to bythemsgp 
argument. If the message text has length greater than msgsz, then if the ms gf i g argument asserts msgnoerror, the message text 
will betruncated (and thetruncated part will belost); otherwise, the message isn't removed from the queue and thesystem 
cali fails, returning with ermo Set tO E2BIG. 

The argument ms gt y p specifies the type of message requested as follows: 

If msgtyp iso, themessageon the queue's front isread. 

If msgtyp is greater than a, the first message on the queue of type msgtyp is read if msg_except isn't asserted by the ms gf i g 
argument; otherwise, the first message on the queue of type not equal to msgtyp will beread. 

If msgtyp islessthan 0, the first message on the queue with the lowest type less than or equal to the absolute value of msgtyp 
will beread. 

The ms g f i g argument asserts none, one, or more (OR- ing them) among the followi ng flags: 

ipc_nowait For immediate return if no message of the requested type is on thequeue. Thesystem cali 

fails With ermo Setto ENOMSG. 

msg_except Used with msgtyp greater than 0 to read the first message on the queue with message type 

that differs from msgtyp. 
msg_noerror T o torneate the message text if longer than ms g s z bytes. 
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If no message of the requested type isavailable and ipcjiowait isn'tasserted in ms gf i g , the calli ng process is blocked until one 
of thefollowing conditionsoccurs: 

A message of the desi red type is placed on the queue. 

The message queue is removed from thesystem. In such a case the system cali failswith ermo setto eidrm. 

The calling process receives a signal that hasto becaught. In such a case the system cali failswith ermo setto eintr. 

Upon successful completion, the message queue data structureisupdated asfollows: 
msg_irpid Set to the process D of the calling process. 

msg_qnum D ecremented by 1. 

msg_rtime Set to the current ti me. 

RETURN VALUE 

On afailure, both functions return -1 with ermo indicating the errar; otherwise, msgsnd returnso and msgrvc returnsthe 
number of bytes actually copied into themtext array. 

ERRORS 

When msgsnd fai Is, at return ermo will be setto oneof thefollowing values: 

eagain T he message can't besent dueto the msg_qbytes limitfor the queue and ipc_nowait was 

asserted in mg s f i g . 

eacces The calling process has no write access permissionson the message queue. 

efault Theaddresspointed to by msgp isn'taccessible. 

eidrm The message queue was removed. 

eintr Sleepingon a full message queue condition, the process received asignal that had to be 

caught. 

einval Invalid msqj d value, or nonpositivemt ype value or invalid msgsz value (less than 0 or greater 

than thesystem value msgmax). 
enomem Thesystem hasnotenough memoryto make a copy of thesupplied msgbuf. 

When msgrcv fai Is, at return ermo will be setto oneof thefollowing values: 

e2big The message text length isgreaterthan msgsz and msg_noerror isn'tasserted inmsgfig. 

eacces The calling process has no read access permissionson the message queue 

efault Theaddresspointed to by msgp isn'taccessible. 

eidrm Whiletheprocesswassleepingto receive a message, the message queue was removed. 

eintr Whiletheprocesswassleepingto receive a message, the process received asignal that had to 

becaught. 

einval lllegal msgqi d value ormsgsz lessthan 0. 

enomsg ipc_nowait was asserted in ms gf i g and no message of the requested type existed on the 

message queue 

NOTES 

T he followings are system limitsaffecting amsgsnd system cali: 

msgmax M aximum sizefor a message text; the implementati on set this value to 4080 bytes. 

msgmnb Default maximum sizein bytes of a message queue: policy dependent. Thesuperuser can 

increasethesizeof a message queue beyond msgmnb by amsgcti system cali. 

Theimplementation has no intrinsic limits for the systemwide maximum number of message headers (msgtql) and forthe 
systemwide maximum sizein bytes of the message pool (msgpool). 
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SEEALSO 

ipc(5), msgctl(2), msgget(2), msgrcv(2), msgsnd(2) 

Linux 0.99.13, 1 Novemberl993 

msync 

msync — Synchronizes a fi le with a memory map 
SYNOPSIS 

#include <unistd.h> 
#include <sys/mman.h> 

#ifdef_POSIX_MAPPED_FILES 
#ifdef_POSIX_SYNCHRONIZED_IO 

int msync (const void *st a r t , size_t I engt h , int f I a g s ) ; 

#endif 

#endif 

DESCRIVO N 

msync flushes changes made to the in-core copy of afilethatwasmapped into memory usi ngmmap(2) back to disk. W ithout 
use ofthis cali, thereis no guaranteethat changes are written back beforemunmap(2) iscalled. To be more precise, thepart of 
thefilethat correspondsto the memory area starti ng at start and having length i engt h isupdated. Thef i ags argument may 
havethe bitSMs_ASYNc, ms_sync, and ms_invalidate set, but not both msj\sync and ms_sync. ms_async specifies that an update 
bescheduled, but the cali returnsimmediately. ms^sync asksfor an update and waitsfor itto complete. ms_invalidate asksto 
invalidate other mappingsof thesamefile(so that they can beupdated with thefresh vai ues just written). 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and ermo isset appropriately. 
ERRORS 

einval start is not a multi pie of pagesize, or any bit other than ms_async | ms_invalidate | 

MS_SYNC iSSet in f I ags . 

efault Theindicated memory (or partof it)was not mapped. 

CONFO RMSTO 

posix.4. 

SEEALSO 

mma P (2), B.O . Gallmeister, POSIX.4, 0 'Rally, pp. 128-129, 389-391. 

Linux 1.3.86, 12 Aprii 1996 

munlock 

muniock— Reenables paging for some parts of memory 
SYNOPSIS 

#include <sys/mman.h> 

int munlockfconst void *addr, size_t len); 
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muniock reenables pagingfor thememory in the range starti ng ataddr with length i en bytes. Ali pagesthat contai n a part of 
thespecified memory range can after cali ing muniock bemoved to external swap space again by the kernel. 

M emory locksdo not stack, that is, pagesthat havebeen locked several times by Calisto miock or miockaii will beunlocked 
by a single cali to muniock for the corresponding range or by muniockaii. Pagesthat are mapped to several locationsor by 
several processes stay locked into RAM as long asthey are locked at least at one location or by at least one process. 

On POSIX systems on which mlock and muniock areavailable _POSIX_M EM LOCKRAN GE isdefined in <unistd.h> 
and thevaluePAGEsizE from <iimits.h> indicatesthenumber of bytes per page 

RETURN VALUE 

On success, muniock returnse. On error, -1 isreturned, ermo isset ap propri atei y, and no changesaremadeto any locksin 
the address space of the process 

ERRORS 

enomem Some of thespecified address range does not correspond to mapped pagesin the address 

space of the process. 
einval en wasnota positive number. 

STANDARD S 

POSIX.lb, SVR4 

SEEALSO 

mlock(2), mlockall(2), munlockall(2). 

Linux 1.3.43, 26 N ovember 1995 

muniockaii 

muniockaii— Reenables pagi ng for calli ng process 
SYNOPSIS 

#include <sys/mman.h> 
int munlockall(void) ; 

D ESC RIPTIO N 

muniockaii reenables paging for ali pages mapped into the address space of the cai I i ng process. 

M emory locksdo not stack, that is, pagesthat havebeen locked several timesby Calisto miock or miockaii will beunlocked 
by a single cali to muniockaii. Pagesthat are mapped to several locationsor by several processes stay locked into RAM as long 
asthey are locked at least at one location or by at least one process. 

On POSIX systemson which miockaii and muniockaii areavailable, _posix_memlock isdefined in <uni std. h>. 
RETURN VALUE 

On success, muniockaii returnsa. On error, -1 isreturned and ermo isset appropriately. 

STANDARD S 

POSIX.lb, SVR4 
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SEEALSO 

mlockall(2), mlock(2), munlock(2) 

Linux 1.3.43, 26 N ovember 1995 

nanosleep 

nanosleep— Pauses execution for a specified ti me 
SYNOPSIS 

#include <time.h> 

int nanosleep(const struct timespec *r e q , struct timespec *rem); 

D ESC RIPTIO N 

nanosleep delaystheexecution of the program for at least the ti me speci fi ed in x r eq .The function can return earlier if a signal 
hasbeen delivered to theprocess. In thiscase, it returns -1, setserrno to eintr, and writesthe remaining timeinto the 
structure pointed to by rem unlessr em ìsnull. Thevalueof 'rem can then beused to cali nanosleep again and complete the 
specified pause. 

The structure ti mespec isused to specify intervalsof timewith nanosecond precision. It is specified in <t i me. h> and hasthe 
form 

struct timespec 
{ 

time_t tv_sec; /* seconds */ 
long tv_nsec; /* nanoseconds */ 

>; 

Thevalueof the nanoseconds fi dd must bein therangeO to 999 999 999. 

Compared to sieep(3) and usieep(3), nanosleep has the advantage of not affecting any signals; it is stand ardized by POSIX, it 
provides higher timing resolution, and it allowsto continue a sleep that hasbeen interrupted by a signal moreeasily. 

ERRO RS 

In caseof an erroror exception, the nanosleep system cali returns -1 instead of e and setserrno to oneof thefollowing values: 

eintr The pause hasbeen interrupted by a nonblocked signal that was delivered to theprocess. 

The remaining sleep time hasbeen written into *r e m so that the process can easily cali 

nanosleep again and continue with the pause. 
einval Thevaluein thet v _ n s e c field was not in therangeO to 999 999 999 ort v.sec was negative. 

BUGS 

Thecurrent implementation of nanosleep isbased on thenormal kernel timer mechanism, which has a resolution of 1/H Z s 
(that is, lOmson Linux/i386 and lmson Linux/Alpha). Therefore, nanosleep pauses always for at least the speci fi ed time; 
however, it can takeup to lOms longer than specified until theprocess becomes runnable again. For thesamereason, the 
valuereturned in caseof a delivered signal in *r em is usuai ly rounded to thenext larger multiple of 1/H Z s. 

Becausesomeapplicationsrequiremuch more precise pauses (for example, in orderto control sometime-critical hardware), 
nanosleep isalso capable of short high-precision pauses. If the process isscheduled under a real-time policy such as 
sched.fi fo or se hed.rr, then pauses of up to 2mswill beperformed asbusy waitswith microsecond precision. 

STANDARD S 



POSIX. lb 
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SEEALSO 

sleep(3), usleep(3), sched_setscheduler(2), timer_create(2) 

Linux 1.3.85, 10 Aprii 1996 

nice 

nice— C hanges process priori ty 
SYNOPSIS 

#include <unistd.h> 
int nice(int ine); 

DESCRIPTION 

nice addsi ne to the priority for the calli ng PID . Notethat only thesuperuser may speci fy a negative increment, or priority 
increase. N otethat internally, a higher number isa higher priority. Do not confuse thiswith the priority schemeasused by 
the nice interface. 

RETURN VALUE 

On success, 0 isreturned. On error, -1 isreturned and ermo isset appropriately. 
ERRORS 

eperm A nonsuperuserattemptsto do a priority increase, anumerical decrease, bysupplyinga 

negative i ne. 

CONFO RMSTO 

SVID EXT, AT&T, X/OPEN, BSD 4.3 

SEEALSO 

nice(l), setpriority(2), fork(2), renice(8) 

Linux, 28 M arch 1992 

oldf stat, oldlstat, oldstat, oldolduname, olduname 

oldfstat, oldlstat, oldstat, oldolduname, olduname— 0 bsolete System calls 

SYNOPSIS 

Obsolete system calls. 

DESCRIPTION 

The Linux 1.3.6 kernel implementsthese Calisto support old executables. Th esecai Is return structuresthat havegrown since 
theirfirst implementations, but old executables must conti nueto receive old smaller structures. 

Current executables should belinked with current librari es and never use these calls. 
SEEALSO 

fstat(2), lstat(2), stat(2), uname(2), undocumented(2), unimplemented(2) 

Linux 1.3.6, 22 July 1995 
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open, creat 



0_CREAT 
0 EXCL 



0_TRUNC 
0 APPEND 



open, creat— Open and possibly create a fi le or device 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 

int open(const char *pat hname , int flags); 

int open(const char *pat hname , int flags, mode_t mode); 

int creat(const char *pat hname ,mode_t mode); 

D ESC RIFTIO N 

open attemptsto open a file and return afiledescriptor (asmall, nonnegative integer for use in read, write, and so on). 
flags isoneof o_rdonly, o_wronly, or o_rdwr, which request opening the file read-only, write-only, or read/write, respectively. 
flags may also PePitwise-oRed with oneor more of the following: 

If the fi le does not exist it wi II Pe created. 

When used with o_creat, if thef ile al ready exists, it isan errar and the open will fail. Seethe 
"Bugs" section, though. 

If pattinarne refers to a terminal device- see tty(4>— it will not Pecometheprocess's 
controlli ng terminal even if the process does not haveone 
If the file already exists, itwill Petruncated. 

Thefileisopened in append mode. Ini ti al ly, and Peforeeach write, the fi le pointer is 
positioned attheend of thefile, asif with iseek. 

Thefileisopened in nonPIocking mode. N either the open noranysuPsequentoperationson 
the fi le descri ptor that isreturned will cause the cai ling process to wait 
Thefileisopened forsynchronousl/O. Anywriteson the resulti ng fi le descri ptor will 
Plock the calli ng process unti I the data hasPeen physically written to theunderlying 
hardware. Seethe "Bugs" section, though. 

Some of these optional flags can Pealtered usi ng tenti after the file has been opened. 

mode specifies the permissions to useif a new fi le is created. It ismodified Py theprocess'sumask in the usuai way: The 
permission of the created file is (mode & 'umask). 

The following symPolic constantsareprovided for mode: 

00700 user (file owner) has read, write and execute permission. 
00400 user has read permission. 
00200 user has write permission. 
00100 user has execute permission. 
00070 group has read, write, and execute permission. 
00040 group has read permission. 
00020 group has write permission. 
00010 group has execute permission. 
00007 others haveread, write, and execute permission. 
00004 others have read permission. 
00002 others have write permission. 
00001 others have execute permission. 

mode should always be specified when o_creat isin the fi a g s , and isignored otherwise. 
creat is equivalent to open with 1 1 ags equal to o_creat|o_wronly|o_trunc. 



O NONBLOCK OTO NDELAY 



O SYNC 



S_IRWXU 

SJRUSR (S_IREAD) 

SJWUSR (S_IWRITE 

SJXUSR (S_IEXEC) 

S_IRWXG 

SIRGRP 

S_IWGRP 

SIXGRP 

S_IRWXO 

S_IR0TH 

S_IW0TH 

S IXOTH 
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RETURN VALUE 

open and creat return thenew fi le decriptar, or -1 if an errar occurred (in which case ermo isset appropriately). N otethat 
open can open device-special files, but creat cannot create them— use mknod(2) instead. 



ERRORS 

EEXIST 
EISDIR 
ETXTBSY 

EFAULT 
EACCES 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

EMFILE 

ENFILE 

ENOMEM 

EROFS 

ELOOP 

ENOSPC 



pat hname already exists and o_creat and o_excl wereused. 

pat hname refersto a directory and the access requested involved writing. 

pat hname refersto an executableimage which iscurrently béng executed and wri te access 

was requested. 

pat hname poi nts outside your accessi bleaddress space. 

The requested access to the file is not allowed, or oneof the di rectories in pat hname did not 
allow search (execute) permission. 

pat hname wastOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 

A component used as a directory in pattinarne isnot, in fact, a directory. 

T he process already has the maximum number of fi les open. 

The limit on the total number of fi les open on the system hasbeen reached. 

I nsuffi ci ent kernel memory wasavailable. 

pat hname refers to a fi le on a read-only filesystem and write access was requested. 

pat hname contai ns a referenceto a ci rcular symbolic link, that is, a symbolic link whose 

expansion contai ns a referenceto itself. 

pathname wasto becreated but the device containing pat hname hasno room for thenew fi le. 



CONFO RMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

BUGS 

o_sync isnot currently implemented (asof Linux 0.99pl7). 

There are many infeliciti es in the protocol underlying N FS, affecting amongst otherso_SYNc, ojdelay, and o_append. 

o_excl isbroken on N FSfilesystems; programsthat rely on itfor performing lockingtaskswill contai n a race condì ti on. The 
solution for performing atomi c file locking usi ng a lockfi le isto createauniquefileon thesamets (forexample, incorporat- 
ing hostnameand PID), useiink(2) to makea link to the lockfi le, and usestat(2) on theuniquefileto check if itslink 
count hasincreased to 2. Do not use the return valueof theiink() cali. 

SEEALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), mknod(2), stat(2), umask(2), mount(2), socket(2), socket(2), fopen(3), link(2) 

Linux 0.99.7, 21 July 1993 



outb, outw, outi, outsb, outsw, outsl 



outb, outw, outl, outsb, outsw, outsl— Port Output 

inb, inw, ini, insb, insw, insl — Port input 

outb_p, outw_p, outl_p, inb_p, inw_p, inl_p— Pause I/O 

DESCRIPTION 

Thisfamily of functionsisused to do low-level port input and output. They are pri mari ly designed for internai kernel use, 
but can beused from user space, given thefollowing information in addition to that given in outb(9). 



personal ity 



You compi le with -oor -02 or something similar. Thefunctionsaredefined asinlinemacrosand will not be substituted in 
without optimization enaPIed, causi ng unresolved referencesatlinktime. 

You useioperm(2) or alternatively iopi(2) to teli the kernel to allow the user space application to access the I/O ports in 
question. Fai Iure to do thiswill cause the application to receiveasegmentation fault. 

C0NF0RMST0 

outb and friends are hardware specific. The por t and vai ue argumentsarein theoppositeorder from most DOS implementa- 
ti ons. 

SEEALSO 

outb(9), ioperm(2), iopl(2) 

Linux, 29 N ovember 1995 

pause 

pause— W aitsfor signal 
SYNOPSIS 

#include <unistd.h> 
int pause(void) ; 

DESCRIPTION 

Thepause system cali causestheinvoking processto sleep until asignal isreceived. 

RETURN VALUE 

pause alwaysreturns-1, and ermo is setto erestartnohand. 

ERRORS 

eintr Signal wasreceived. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

kill(2), select(2), signal(2) 

Linux, 31 August 1995 

personality 

personaiity— Sets the process execution domain 
SYNOPSIS 

int personality(unsigned long persona); 

DESCRIPTION 

Linux supports different execution domains, or personali ties, for each process. Amongother things, execution domai ns teli 
Linux how to map signal numPersinto signal acti ons. The execution domain system allows Linux to provide li mi ted support 
for binari es compi led under other U N IX-like operati ng systems. 

personality will maketheexecution domain referenced by persona thenew execution domain of thecurrent process. 
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RETURN VALUE 

On success, persona is madethe new execution domain and the previousper sona isretumed. On errar, -1 isreturned and 
ermo is set appropri ately. 

ERRORS 

einval persona does not refer to a valid execution domain. 

FILE 

/usr /include/ linux /personality.h 

C0NF0RMST0 

personality ÌS Linux Specific. 

Linux 2.0, 22 July 1996 

phys 

phys— Allowsa processto access physi cai addresses(thiscommand isnot implemented) 
SYNOPSIS 

int phys(int physnum, char "virtaddr, longsize, char *physaddr); 

DESCRIPTION 

Warning: Becausethisfunction isnot implemented asof Linux 0.99.11, it will always return -1 and set ermo to enosys. 

phys mapsarbitrary physical memory into a processavi rtual address space, physnum isa number (0-3) that specifieswhich of 
thefour physical spacesto set up. Up to four phys calls can beactiveat any onetime virtaddr istheprocess's virtual address. 
size isthe number of bytesto map in. physaddr isthe physical address to map in. 

Valid virtaddr and physaddr values are constrained by hardware and must beat an address multiple of the resolution of the 
CPU's memory management schema If size is nonzero, sizeisrounded up to thenext M M U resolution boundary. If size i s 
a, any previousphys(2) mappingforthat physnum isnullified. 

RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned and ermo is set appropriately. 

C0NF0RMST0 

versi on 7 AT&T UNIX 

BUGS 

phys isvery machine dependent. 
SEEALSO 

mmap(2), munmap(2) 

Linux 0.99.11, 24 July 1993 

pipe 

pipe— C reates a pipe 




SYNOPSIS 

ffinclude <unistd.h> 

int pipe(int filedes[2] ) ; 

DESCRIPTION 

pipe createsa pair of fi le descriptors, pointing to a pipeinode, and placesthem in thearray pointed to by medes. fiiedes[B] 
isfor reading, fiiedesrj] isfor writing. 

RETURN VALUE 

On success, 0 isretumed. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

emfile Too many fi le descriptors are in use by the process. 

enfile Thesystem fi le table i s fui I . 

efault fiiedes isnot valid. 

SEEALSO 

read(2), write(2), fork(2), socketpair(2) 

Linux 0.99.11, 23 July 1993 

prof il 

proni— Execution timeprofile 
SYNOPSIS 

#include <unistd.h> 

int profili char *buf , int buf s i z ,int offset , int scale); 

DESCRIPTION 

U nder Linux 0.99.11, prof il isnot implemented in the kernel. Instead, theD LL 4.4.1 libraries provide a user-space 
impietri entation. 

buf pointsto buf si z bytesof core. Every virtual 10 milliseconds, the user's program counter (PC) isexamined: offset is 
subtracted and theresult ismultiplied byscai e. If thisaddressisin buf, the word pointed to isincremented. 

If se ai e islessthan 2 or buf si z i sa, profiling isdisabled. 

RETURN VALUE 

0 isalwaysreturned. 

BUGS 

prof ii cannot beused on a program that al so uses itimer_prof itimers. 
Calling profii with an invalici buf will resultin acoredump. 
True kernel profiling provides more accurate results. 

SEEALSO 

gprof(l), setitimer(2), signal(2), sigaction(2) 

Linux 0.99.11, 23 July 1993 
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ptrace 

ptrace— Process trace 
SYNOPSIS 

#include <sys/ptrace.h> 

int ptrace(int r e q u e s t ,int pi d ,int a d d r ,int data); 

D ESC RIPTIO N 

ptrace provides a means by which a parent process can control theexecution of achild process and examineand changeits 
coreimage. Itsprimary use isfor theimplementation of breakpoint debugging. A traced process runsuntil asignal occurs. 
Then it stopsand the parent is noti fi ed with wait(2). W hen the process is in thestopped state, itsmemory can beread and 
written. The parent can al so cause the chi Id to conti nueexecution, optionally ignori ng the signal which caused stopping. 

The value of the request argument determi nes the precise action of the system cali : 



PTRACE_TRACEME 


This process isto be traced by its parent. The parent should beexpecting to trace the child. 


PTRACE_PEEKTEXT, 


Read word at location addr . 


PTRACE_PEEKDATA 




PTRACE_PEEKUSR 


Read word at location addr in the user area. 


PTRACE_POKETEXT, 


Writeword at location addr . 


PTRACE_POKEDATA 




PTRACE_POKEUSR 


Writeword at location addr in theusER area. 


PTRACE_SYSCALL, 


Restart after signal. 


PTRACE_CONT 




PTRACE_KILL 


Send the child a sigkill to makeit exit. 


PTRACE_SINGLESTEP 


Set the trap flag for single stepping. 


PTRACE_ATTACH 


Attach to the process specified in pi t. 


PTRACE_DETACH 


D etach a process that was previously attached. 



NOTES 

init, the process with process ID 1, maynot use this function. 
RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 



ERRORS 

eperm The specified process (that is, init), cannot be traced or isalready being traced. 

esrch T he specified process doesnotexi st. 

eio Request is notvalid. 



C0NF0RMST0 

SVID EXT, AT&T, X/OPEN, BSD 4.3 

SEEALSO 

gdb(l), exec(2), signal(2), wait(2) 

Linux 0.99.11, 23 July 1993 



quotarti 



quotactl 

quotacti— M ani pulates di sk quotas 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/quota.h> 

int quotarti (int cmd, const char *s peci al , intid , caddr_t a d d r ) ; 
#include <linux/unistd.h> 

syscall4(int, quotarti, int, cmd, const char *, special ,ìnt, id, caddr_t, addr); 

D ESC RIPTIO N 

The quota system definesforeach user or group a soft limit and a hard limit boundingtheamount of disk space thatcan be 
used on agiven filesystem. The hard limit cannot becrossed. The soft limit can becrossed, but warningswill ensue. 
M oreover, the user cannot beabove the soft limit for morethan oneweek (by default) at a ti me After thisweek the soft limit 
countsasa hard limit. 

Thequotacti system cali manipulatesthese quotas. Its first argument isof theform 

QCHD(subcmd.type) 

where type is either usrquota or grpquota (for user quota and group quota, respectivdy. 
Thesecond argument special is the block special devi ce these quotas applyto. It must bemounted. 
Thethird argument ID istheuser or group ID these quotas apply to (when relevant). 
Thefourth argument, addr , istheaddressof a data structure, dependi ng on thecommand. 
Thesubcmd isoneof thefollowing: 

q_quotaon Enables quotas. The addr argument is the pathname of the file containing the quotasfor the filesystem. 

q_quotaoff D isables quotas. 

q_getquota G ets li mits and current usageof disk space. The addr argument is a pointer to adqbik structure 

(defined in <sys/quota.h>). 

q_setquota Sets limits and current usage; addr isasbefore. 

q_setqlim Sets limits; addr isasbefore. 

q_setuse Sets usage. 

q_sync Syncsdisk copy of a filesystem's quotas. 

q_getstats G ets collected state 

RETURN VALUE 

On success, quotactl returnss. On error, -1 isreturned and ermo is set appropriately. 
ERRORS 



ENOPKG 


Thekernel was compiled without quota su pport. 


E FAULT 


Bad addr value. 


EINVAL 


type isnot a known quota type. Or special could not befound. 


ENOTBLK 


special isnot a block special device. 


ENODEV 


s peci ai cannot befound in themounttable. 


EACCES 


T he quota file is not an ordì nary file. 


EIO 


Cannot read or writethequota file. 


EMFILE 


Too many open files: C annot open quota file. 
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ebusy q quotaon was asked, but quota were enabled already. 

esrch q_getquota or q_setquota or q_setuse or q_setqlim was asked for a f i lesystem that didn't have quota 

enabled. 

eperm Theprocesswasnot root (for the fi lesystem), and q_getquota was asked for another ID than that of the 

process itself, or anything other than q_getstats or q_sync was asked. 

C0NF0RMST0 

BSD 

Linux 1.3.88, 14 Aprii 1996 



read 

read— Readsfrom a file descri ptor 
SYNOPSIS 

#include <unistd.h> 

ssize_t read(int f d , void*b u f , size_t count); 

D ESC RIFTIO N 

reado attemptsto read upto count bytesfrom fi le descri ptor fd into the buffer starti ngatbuf. 

If count ÌS0, reado returnse and hasno other results. If count isgreater than ssize_max, theresult isunspecified. 

RETURN VALUE 

On success, thenumber of bytesread is returned (0 indicatesend of file) and thefile position isadvanced by thisnumber. It 
isnotan errar if thisnumber issmaller than thenumber of bytesrequested; thismay happen, forexample, becausefewer 
bytes are actually availableright now (maybebecausewewerecloseto end-of-fileor becausewearereadingfrom a pipe, or 
from a terminal), or because read ( ) wasinterrupted by a signal. On errar, -1 is returned and ermo is set appropriate^. In this 
caseit is left unspecified whether thefile position (if any) changes. 

ERRORS 

eintr Thecall wasinterrupted by a signal before any data was read. 

eagain N on-blocking I/O hasbeen selected usingo_NONBi_ocK and no data was immediately availablefor 

read ing. 

eio I/O errar. Thiswill happen, forexample, when the process is in a background processgroup, triesto 

read from its controll ingtty, and it is ignori ng or blockingsiGTTiN or its processgroup isorphaned. 
eisdir f d refers to a di rectory. 

ebadf fd isnot a valid fi le descri ptor or is not open for reading. 

einval fd isattached to an object that isunsuitablefor reading. 

efault buf isoutsideyouraccessibleaddressspace. 

Other errorsmay occur, dependi ngon the object con nected to fd. POSIX allowsa read that is interrupted after reading some 
datato return -1 (with ermo setto eintr) orto return the numberof bytes al ready read. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN, BSD 4.3 

SEEALSO 

readdir(2), write(2), write(2), f cntl(2), close(2), lseek(2), select(2), readlink(2), ioctl(2), f read(3) 

Linux, 17 J anuary 1996 
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readdir 

readdir— Reads directory entry 
SYNOPSIS 

#include <unistd.h> 
#include <linux/dirent.h> 
#include <linux/unistd.h> 

syscall3(int, readdir, uint, fd, struct dirent *, dirp, uint, count); 
int readdir(unsigned int fd, struct dirent *dirp, unsigned int count); 



DESCRIPTION 

Thisisnotthefunction you are interested in. Look at readdir(3) for thePOSIX-conforming C library interface. This page 
documentsthe bare kernel system cali interface which can change, and which issuperseded by getdents(2). 

readdir readsone dirent structure from the directory pointed at by fd into the memory area pointed to by di rp.The 
parameter count is ignored; at most one dirent structure is read. 

Thedirent structure is declared asfollows: 

struct dirent 
{ 

long d_ino; /* inode number */ 

off_t d_off; /* offset to this dirent */ 

unsigned short d_reclen; /* length of this d_name */ 

char d_name [NAME_MAX+1 ] ; /* file name (null-terminated) */ 

} 

d_i no isan inode number. d.off is the distance from the start of the directory to this dirent. d _ r e c i en is the sizeof d_ name, not 
counti ng the nuli terminator. d_name isa null-terminated filename. 

RETURN VALUE 

On success, 1 isreturned. 0 n end of directory, 0 isreturned. On errar, -1 isreturned and ermo isset appropriately. 
ERRORS 

ebadf Invalid filedescriptor fd. 

enotdir F ile descri ptor does not refer to a di rectory. 

C0NF0RMST0 

Thissystem cali is Linux speci fic. 

SEEALSO 

getdents(2), readdir(3) 

Linux 1.3.6, 22 July 1995 



readlink 

readlink— Reads value of a symbolic link 
SYNOPSIS 



#include <unistd.h> 

int readlink(const char *path, char *buf , size_t bufsiz); 
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DESCRIPTION 

readiink places the contents of the symbol ic link path in the buffer b u f , which hassizebuf si z . Readlink does not append a 
nul character to buf . 

RETURN VALUES 

The cali returnsthecount of characters placed in the buffer if it succeeds, or a-1 if an errar occurs, piaci ng the errar code in 
theglobal variableerrno. 

ERRORS 

enotdir A componentof the path prefix is not a directory. 

einval T he pathnamecontains a character with the high-order bit set. 

enametoolong A component of a pathname exceeded 255 characters, or an enti re path nameexceeded 1023 
characters. 

enoent Thenamedfiledoesnotexist. 

eacces Search permission isdenied fora componentof the path prefix. 

eloop Too many symbolic linkswereencountered in translati ng the pathname 

einval Thenamed fi le is not a symbolic link. 

eio Anl/O errar occurredwhi le readingfrom thefilesystem. 

efault buf extends outside the process's ali ocated address space. 

HI STORY 

The readiink function cali appeared in BSD 4.2. 
SEEALSO 

stat(2), lstat(2), symlink(2) 



BSD M an Page 24 J uly 1993 



readv, writev 

readv, writev— Reads or writes a vector 
SYNOPSIS 

#include <sys/uio.h> 

int readv(int fd, const struct iovec * vector, sizej: count); 
int writev(int fd, const struct iovec * vector , size_t count); 
struct iovec { 

ptr_t iovbase; /* Starting address. */ 
size_t o v _ I e n ; /* Length in bytes. */ 

>; 



DESCRIPTION 

readv readsdata from fi le descri ptor f d and puts the result in the buffers described by vector . The numberof buffers is 
specified by count . The buffers are fi lied in theorder specifi ed. Operatesjust likeread except that data is put in vector 
instead of a conti guous buffer. 

writev writes data to file descriptor f d , and from the buffers described by vector. The num ber of buffers is specified by count . 
The buffers are used in theorder specified. Operatesjust likewrite except that data istaken from vector instead of a 
conti guous buffer. 



readv, writev 




RETURN VALUE 

On success, readv returnsthenumber of bytesread. On success, writev returnsthenumberof byteswritten. On error, -1 is 
returned, and ermo isset appropriately. 

ERRORS 

einval An invalid argument was given. For instancec ount might begreaterthan max_iovec, oro. f d could 

also beattached to an object that isunsuitablefor reading. 
efault Segmentation fault. M ost likely«ect or orsomeof thei ov.base poi nters poi nts to memory that is 

not properly allocateci. 
ebadf Thefile descriptor f d isnotvalid. 

eintr The cali was interrupted byasignal beforeany data was read/written. 

eagain N on-blocking I/O hasbeen selected using o nonblock and no data was immediately availablefor 

reading. (0 r thefile descriptor fd isforan object that islocked.) 
eisdir f d refers to a di rectory. 

eopnotsup f d refers to a socket or device that does not support reading/writing. 

Other errorsmay occur, depending on the object connected to f d . 

SEE ALSO 

read(2), write(2), fprintf(3), fscanf(2) 

Linux 1.3.86, 12 Aprii 1996 

reboot 

reboot— Reboots or disables C tri +Alt+D el 
SYNOPSIS 

#include <unistd.h> 

int reboot ( int ma g i c , int ma g i c _ t o o , int f I a g ) ; 

DESCRIVO N 

reboot reboots the system orenables/disablesCAD. 

If magic =0xfeeidead and magic too =672274793, the action performed will bebased on f I ag. 

If fiag=oxi 234567, a hard reset is performed. 

If fiag=8x89abcdef, CAD isenabled. 

If fiag=0, CAD isdisabled and a signal issentto processi D 1. 

N Ote that reboot ( ) does not sync ( ) ! 

Only thesuperuser may usethisfunction. 
RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned, and ermo isset appropriately. 
ERRORS 

einval Badmagi c numbersorf I ag. 

eperm A non-root user hasattempted to cali reboot. 
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CONFORMSTO 

reboot is Linux specific. 

SEEALSO 

sync(2), ctrlaltdel(8), halt(8), reboot(8) 

Linux 0.99.10, 28 March 1992 



recv, recvfrom, recvmsg 

recv, recvfrom, recvmsg— Receives a message from a socket 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/socket.h> 

int recv(int s , void *buf , intl en , unsigned int f I ags ) ; 
int recvfrom(int s, void*b u f , int I e n , unsigned int fi ags, 

struct sockaddr *f r o m , int *fromlen); 
int recvmsg(int s, struct msghdr *msg, unsigned int flags); 

DESCRIPTION 

Warning: Thisisa BSD man page. As of Linux 0.99.11, recvmsg was not implementai. 

recvfrom and recvmsg areused to recei ve messages from a socket, and may beused to receivedataon a socket whether or not 
it isconnection oriented. 

If f rom isnon-nil, and the socket is not connection-oriented, the sourceaddressof the message is fi lied in. f r o mi en isavalue- 
result parameter, initialized to the sizeof the buffer associated with from and modified on return to indicate the actual sizeof 
theaddressstored there. 

The recv cali isnormally used only on aconnected socket (seeconnect(2)) and isidentical to recvfrom with a nil from 
parameter. Becauseit isredundant, it might not besupported in future releases. 

Ali threeroutines return the length of the message on successful completi on. If a message istoo longto fit in the supplied 
buffer, excessbytes might bediscarded depending on thetypeof socket from which the message is recei ved (seesocket(2)). 

If no messages are availableat the socket, the recei ve cali waitsfor a message to arrive— unless the socket is nonblocking (see 
fcnti(2)), in which case the value-1 isreturned and theexternal vari able ermo is setto ewouldblock. The recei ve calls 
normally return any data available, up to the requested amount, rather than wait for recei pt of thefull amount requested; 
thisbehavior isaffected by thesocket-level optionsso_Rcvi_owAT and so_rcvtimeo, described in getsockopt(2). 

Theseiect(2) cali may beused to determi ne when more data arri ves. 

Thef i ags argument to a recv cali is formaci by oringoneor more of the values: 

msg_oob Processout-of-band data 

msg_peek Peek at incoming message 

msgjvaitall W ait for full request or errar 

T he msgoob flag requests recei pt of out-of-band datathatwould not be recei ved in thenormal data stream. Someprotocols 
place expedi ted data at the head of thenormal dataqueue; thusthisflag cannot beused with such protocols. TheMSG_PEEK 
flag causes the recei ve operation to return data from thebeginning of the recei ve queuewithout removi ng that data from the 
queue; thus, a subsequent recei ve cali will return the same data. The msg_waitall flag requests that the operation block until 
thefull request issati sfied. H owever, the cali might stili return less data than requested if asignal iscaught, an errar or 
disconnectoccurs, orthenext datato bereceived isof adifferenttypethan that returned. 



recv, recvfrom, recvmsg 



The recvmsg cali usesamsghdr structureto minimizethenumber of di rectly supplied parameters. This structure hasthe 
following form, asdefined in sys/socket.h: 

struct msghdr { 

caddr_t msg_name; /* optional address */ 

u_int msg_namelen; /* size of address */ 

struct iovec *msg_iov; /* scatter/gather array */ 

u_int msg_iovlen; /* # elements in msg_iov */ 

caddr_t msg_control; /* ancillary data, see below */ 

u_int msg_controllen; /* ancillary data buffer len */ 

int msg_flags; /* flags on received message */ 



H eremsg^name and msgjiameien specify the desti nation address if thesocket isunconnected; msg_namemay begiven asa nuli 
pointer if no names are desi red or required. msg_iov and msg_iovien describescatter gather locations, asdiscussed in read(2). 
msg_controi, which has length msg_controiien, pointsto a buffer for other protocol control- rei ated messagesor other 
miscellaneous ancillary data. The messages are of the form 

struct cmsghdr { 

u_int cmsg_len; /* data byte count, including hdr */ 

int cmsg_level; /* originating protocol */ 

int cmsg_type; /* protocol-specif ic type */ 
/* followed by 

u_char cmsg_data[ ] ; */ 



You could use this, for example, to learn of changesin the data stream in XN S/SPP, or in ISO, to obtain user- 
connection-request data by requesti ng a recvmsg with no data buffer provided immediately after an accept cali. 

Open file descriptors are now passed as ancillary data for afjjnix domain sockets, with cmsg_ievei set to sol_socket and 

cmsg_type Set tO SCM_RIGHTS. 

Themsg_fiags field is set on return accordi ngto the message received. msg_eor indicates end-of-record; thedata returned 
completed a record (general lyused with sockets of type sock_seqpacket). msg_trunc indicatesthat the trai ling portion of a 
datagram wasdiscarded because the datagram waslargerthan the buffer supplied. msg_ctrunc indicatesthat somecontrol 
data wasdiscarded dueto lack of space in the buffer for ancillary data. msg_oob is returned to indicate that expedi ted or out- 
of-band data was received. 



}; 



}; 



RETURN VALUES 

These cai Is return the number of bytes received, or -1 if an errar occurred. 



ERRORS 



EWOULDBLOCK 



EBADF 



ENOTCONN 



ENOTSOCK 



EFAULT 



EINTR 



Theargument s isan invalid descriptor. 

Thesocket is associ ated with aconnection-oriented protocol and hasnot been connected (see 

connect(2) and accept(2)). 

The argument s does not refer to a socket. 

Thesocket is marked non-blocking, and the reca ve operati on would block, or a recei ve timeout 

had been set, and thetimeout expired beforedata was received. 

The recei ve was i nterru pted by del i very of a si gn al bef o re any data was avai I abl e. 

T he receive buffer pointer! s) point outside the process's address space 



HI STORY 



These function callsappeared in BSD 4.2. 
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SEEALSO 

fcntl(2), read(2), select(2), getsockopt(2), socket(2) 

BSD Man Page 24 July 1993 

renarne 

renarne— C hanges the name or location of a file 
SYNOPSIS 

#include <unistd.h> 

int rename(const char *ol dpath, const char *newpath); 

DESCRIPTION 

renarne renamesafile, moving it between d i recto ri esif required. 
Any other hard links to thefile(as createci using link) areunaffected. 

If newpat h al ready exists it wi II beautomatically overwritten (subjectto a few condì tions— seethe"Errors" section), so that 
thereisno pointat which another processattemptingto access newpat h will find it missing. 

If newpat h exists but the operation fails for some reason or the system crashes, renarne guaranteesto leavean instanceof 

newpat h in place. 

H owever, when overwriting therewill probably beawindow in which both oi dpat h and newpat h referto thefilebeing 
renamed. 

If oi dpat h refersto a symbol ic link, the link will be renamed; if newpat h refersto a symbolic link, the link will be overwritten. 
RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

eisdir newpat h isan existing directory, but 0 1 dpath is nota directory. 

exdev oi dpath and newpat h are not on thesamefilesystem. 

enotempty newpat h isa non-empty directory. 

ebusy newpat h exists and isthecurrent working directory or root directory of some process. 

einval An attemptwasmadeto make a directory a subdirectory ofitself. 

emlink oi dpath al ready has the maximum number of links to it, or it was a directory and the directory 

containing newpat h has the maximum number of links. 
enotdir A component used as a directory ino dpath or newpat h isnot, in fact, a directory. 

efault oi dpath or newpat h points outside your accessible address space. 

eacces W ri te access to the directory containing oi dpath ornewpath is not allowed for the process's effettive 

UID, or oneof the directories in oi dpat h or newpat h did not allow search (execute) permission, or 
oi dpath was a directory and did not allow write permission (needed to update the . . entry). 

eperm Thedirectorycontainingoi dpath has the sticky bit set, and the process's effecti veli ID isneitherthe 

UID of thefileto bedeleted northatof thedirectory containing it, orthefilesystem containing 
p a t h n a me does not support renami ng of the type requested. 

ENAMETOOLONG o I dpath Or newpat h waStOO long. 

enoent A directory component in oi dpath ornewpath does not exist or isa dangling symbolic link. 

enomem I nsuffi ci ent kernel memory wasavailable. 

erofs Thefileison a read-only filesystem. 
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eloop oi dpath or newpath containsa referenceto a circular symbolic link; that is, asymbolic link whose 

expansion containsa referenceto itself. 
enospc T he device contai ni ng the file has no room forthenew directory entry. 

C0NF0RMST0 

POSIX, BSD 4.3, ANSI C 

BUGS 

Currently (Linux 0.99pl7), most of thefilesystemsexcept M inixwill not allow any overwriting renamesinvolving directories. 
You get eexist if you try. 

On N FS filesystems, you cannot assume that just becausetheoperation failed, the fi le was not renamed. If the server does 
the renarne operati on and then crashes, the retran smitted RPC, which will beprocessed when theserver isup again, causesa 
fai Iure. The application isexpected to deal with this. Seeiink(2) forasimilar problem. 

SEEALSO 

link(2), unlink(2), symlink(2), mv(l), link(8) 

Linux 0.99.7, 24 July 1993 
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rmdir— D eletes a directory 
SYNOPSIS 

#include <unistd.h> 

int rmdir(const char *pat h n a me ) ; 

DESCRIPTION 

rmdir deletesa directory, which must beempty. 

RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

eperm Thefilesystem containing pat h n a me does not support the removal of directories. 

efault pat h n a me poi nts outside your accessi ble address space. 

eacces Write access to the directory contai ni ng pat h nane wasnotallowed for the process'seffecti veli ID, 

or oneof the directories in p a t h n a me did notallow search (execute) permission. 

eperm Thedirectory containing pat tirarne has thesticky bit (s_isvtx) set, and the process'seffecti ve UID is 

neither the U I D ofthefileto bedeleted northatof thedirectory containing it. 

ENAMETOOLONG p a t h n a me was tOO long. 

enoent A directory component in pattinarne does not exist or isa dangling symbolic link. 

enotdir pat h n a me , or acomponent used as a directory in pat ima me, is not, in fact, a directory. 

enotempty pat h n a me contai ns entri es other than . and . . . 

ebusy pat hna me is the current working directory or root directory of some process. 

enomem I nsuffi ci ent kernel memory wasavailable. 

erofs pattinarne refers to a fi le on a read-only filesystem. 

eloop pat hna me contai ns a reference to a ci rcular symbolic link; that is, asymbolic link containing a 
referenceto itself. 
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CONFORMSTO 

SVID.AT&T, POSIX, BSD 4.3 

BUGS 

I nfd icities i n the protocol underlying N FS can cause the unexpected disappearanceof di rectoriesthat are stili beingused. 
SEEALSO 

rename(2), mkdir(2), chdir(2), unlink(2), rmdir(l), rm(l) 

Linux 0.99.7, 24 July 1993 

sched_get_priority_max, sched_get_priority_min 

sched_get_priority_max, sched_get_priority_rain— GetS Stati C priority range 

SYNOPSIS 

#include <sched.h> 

int sched_get_priority_max(int policy); 
int_sched_get_priority_min(int poi i cy); 

D ESC RIPTIO N 

sched_get_priority_max returnsthemaximum priority valuethat can beused with the scheduling algorithm identified by 
poi i cy. sched_get_priority_min returns the mi ni mum priority valuethat can beused with thescheduling algorithm 
identified by poi i cy. Supported poi i cy valuesarescHED_FiFo, sched_rr, and sched_other. 

Processeswith numerically higher priority values are scheduled beforeprocesseswith numerically lower priority vai ues. 
Therefore, thevaluereturned by sched_get_priority_max will begreaterthan thevaluereturned by sched jet jriority_min. 

Linux al lows the stati c priority value range 1 to 99 for sched_fifo and sched_rr, and the priority 0 for sched_other. 
Scheduling priority rangesfor thevariouspoliciesarenot alterable. 

T he range of scheduling prioritiesmay vary on other POSIX systems, so it isagood idea for portable applications to use a 
virtual priority range and map itto the interval given by sched_get_priorìty_max and sched_get_priorityjnin. POSIX.lb 
requiresa spread of at least 32 between the maximum and the minimum values for sched_fifo and schedar. 

POSIX systems on which sched_get_priority_max and sched_get_priority_min are available define 

_POSIX_PRIORITY_SCHEDULING in <unistd.h>. 

RETURN VALUE 

On success, sched_get_priority_max and sched_get_priority_min return the maximum and minimum priority values for the 
named scheduling policy. On errar, -1 isreturned, and ermo isset appropriately. 

ERRORS 

einval Theparameter policy does noti dentify a defi ned scheduling policy. 

STANDARD S 

POSIX.lb (formerlyPOSIX.4) 

SEEALSO 

sched_setscheduler(2), sched_getscheduler(2), sched_setparam(2), sched_getparam(2) 

sched_setscheduier(2) hasa descri ption of the Linux scheduling scheme. 



sched_ rr_ get_ i nterval 

Programming fortheReal World- POSIX.4 by Bill 0. G al Imeister, 0'Reilly& Associates, Inc., ISBN 1-56592-074-0 
I E E E Std 1003. lb- 1003 (PO SI X .lb standard) 
ISO/IEC 9945-1:1996 

Linux 1.3.81, 10 Aprii 1996 

sched_rr_get_interval 

sched_rr_get_intervai— GetsthescHED_RR interval forthenamed process 
SYNOPSIS 

(finclude <sched.h> 

int sched_rr_get_interval(pid_t pid, struct tìmespec *t p ) ; 
struct timespec { 

time_t tv_sec; /* seconds */ 

long tv_nsec; /* nanoseconds */ 

>; 

DESCRIPTION 

sched_rr_get_intervai writesinto the ti mespec structure pointed to by t p the round-robi n ti me quantum for the process 
identified by pi d. If pi d isa, the ti me quantum for the cai li ng process iswritten into *t p. Theidentified process should be 
running under thescHED_RR scheduling policy. 

The round robin ti me quantum valueisnot alterable under Linux 1.3.81. 

POSIX Systems On Which sched_rr_get_interval ÌS available define_POSIX_PRIORITY_SCHEDULING in <unistd.h>. 

RETURN VALUE 

On success scned_rr_get_intervai returnse. O n error, -1 isreturned, and ermo issetappropriately. 
ERR0RS 

esrch The process whoselD ispi d could not befound. 

enosys Thesystem cali isnotyetimplemented. 

STANDARD S 

POSIX.lb (formerly POSIX.4) 

BUGS 

Asof Linux 1.3.81, sched_rr_get_intervai returns with error enosys, because sched_rr has not yet been fui I y implemented or 
test ed prò peri y. 

SEEALS0 

sched^setscheduier(2) has a descri ption of the Linux scheduling scheme. 

ProgrammingfortheReal World- POSIX.4 by Bill O. G al Imeister, 0'Reilly& Associates, Inc., ISBN 1-56592-074-0 
I E E E Std 1003.1b-1993 (POSIX.lb standard) 
ISO/IEC 9945-1:1996 

Linux 1.3.81, 10 Aprii 1996 
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schedjetparam, schedjetparam 

sched_setparam, sched_getparam— Setsand get scheduling parameters 
SYNOPSIS 

#include <sched.h> 

int sched_setparam(pid_t pìd, const struct sched_param *p); 

int sched_getparam(pid_t pid, struct sched_param *p); 
struct schedjaram { 

int se h e d _ pr i or i t y ; 

}; 

D ESC RIPTIO N 

scned_setparam sets the scheduli ng parameters associated with the scheduling policy for theprocess identified bypi t. If pi d is 
a, the parameters of the current process are set. Theinterpretation of theparameter p dependson the selected policy. 
Currently, thefollowing three scheduling policiesaresupported under Linux: sched_fifo, sched_rr, and sched_other. 

sched_getparam retrieves the schedul ing parameters for the process identified by pi d. If pi d iso, the parameters of the current 
process are retri eved. 

sched_setparam checksthe validity of p fortheschedulingpolicyof theprocess. Theparameter p->schedjriority must lie 

within the range given by sched_get_priority_min and sched_get_priority_max. 

POSIX Systemson which sched_setparam and sched_getparam areavailabledefine^POSIX_PRIORITY_SCHEDULING in <unistd.h>. 

RETURN VALUE 

On success, sched_setparam and sched_getparam return a. 0 n errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

esrch The process whoselD ispi d could not befound. 

eperm The cali ing process does not have appropriate privi leges. The process cali ing scned_setparam needs 

an effectiveU ID equal to theU ID or UID of theprocess identified by pi d, or it must bea 
superuser process. 

einval Theparameter p doesnotmakesenseforthecurrentschedulingpolicy. 

STANDARD S 

POSIX.lb(formerlyPOSIX.4) 

SEEALSO 

sched_setscheduler(2), sched_getscheduler(2), sched_get_priority_max(2), sched_get_priority_mìn(2), nìce(2), 
setpriority(2), getpriority(2) 

sched_setscheduier(2) hasa description of the Linux scheduling scheme. 

ProgrammingfortheReal World- POSIX.4 by Bill 0. Gallmeister, 0 'Reil ly & Associates, Inc., ISBN 1-56592-074-0 
I E E E Std 1003. lb- 1993 (PO SI X .lb standard) 
ISO/IEC 9945-1:1996 

Linux 1.3.81, 10 Aprii 1996 
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sched_setscheduler,sched_getscheduler 

sched_setscheduier, sched_getscheduier— Setsand gets scheduling algorithm/parameters 
SYNOPSIS 

(finclude <sched.h> 

int sched_setscheduler(pid_t pi d , intpo I i cy , const struct sched_param *p); 
int sched_getscheduler(pid_t pid); 
struct sched_param { 

int s c h e d _ pr i or i t y ; 

}; 

D ESC RIPTIO N 

sched_setscneduier sets both the scheduli ng poli cy and theassociated parametersfortheprocess identified by pi d. If pi d isa, 
thescheduler of the calli ng process will beset. Theinterpretation of theparameter p dependson theselected policy. 
Currently, thefollowingthree scheduling policiesaresupported under Linux: sched_fifo, sched_rr, and sched_other; their 
respectivesemanticsaredescribed in the followi ng section. 

sched_getscheduier queries the scheduling policy currently applied to the process identified by pi d. If pi d ise, the policy of 
the cai I i ng process will beretrieved. 

SCHEDULING PO LICIES 

Thescheduler is the kernel part that decides which runnable process will beexecuted nextby the CPU. The Linux scheduler 
offersthree different scheduling policies, onefor normal processesand two for real-time applications. A stati c priority value, 
sched_pr i ori t y, isassigned to each process, and this value can bechanged only via system calls. Conceptually, thescheduler 
maintainsa list of runnable processes for each possi blese hed_pr ori t y value, and s c h e d _ p r i ori t y can havea value in the 
rangeO to 99. To determi ne the process that runs next, the Linux scheduler looksfor thenon-empty list with the highest 
stati c priority and takes the process at the head of this li st. The scheduling policy determi nes, for each process, whereit will 
beinserted into the list of processes with equal stati c priority and how itwill move inside this list. 

sched_other isthe default uni versai ti me-sharing scheduler policy used by most processes; sched_fifo and sched_rr are 
intended for special, time-criti cai applicationsthatneed precise control overtheway in which runnable processes are sei ected 
for execution. Processes scheduled with sched_other must beassigned the stati c priority 0; processes scheduled under 
sched_fifo or sched_rr can haveastatic priority in therangel to 99. Only processeswith superuser privilegescan get a stati c 
priority higherthan 0 and can thereforebe scheduled under sched_fifo or sched_rr. The system calls scned_get_priority_min 
and sched_get_priority^max can beused to fi nd out thevalid priority range for a scheduling policy in a portableway on ali 
PO SlX.lb-conforming system s. 

Ali scheduling ispreemptive: If a process with a higher stati c priority gets ready to run, thecurrent process will bepreempted 
and returned into its wait list. The scheduling policy determi nes the ordering within the list of runnable processes only 
amongthosewith equal stati c priority. 

SCHEDJIFO: FIRST IN-FIRST OUT SCHEDULING 

sched_fifo can only beused with stati c priorities higherthan 0, which meansthat when a sched_fifo process becomes 
runnable, itwill always preempt immediately any currently running normal sched_other process. sched_fifo isasimple 
scheduling algori thm without ti me si ici ng. 

For processes scheduled under the sched_fifo policy, the followi ng rules are applied: A sched_fifo process that has been 
preempted by another process of higher priority will stay at the head of the list for its priority and will resumé execution as 
soon asall processes of higher priority areblocked again. When a sched_fifo process becomes runnable, itwill beinserted at 
the end of the list for its priority. A cali to sched_setscheduier or scned_setparam will put the sched_fifo process identified by 
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pi d at the end of the list if it wasrunnable. A processcalling sched_yieid will beput at the end of the list. N o other events 
will movea processscheduled under the sched_fifo policy in thewait list of runnableprocesseswith equal stati c priority. A 
sched_fifo processrunsuntil it isblocked by an I/O request, it ispreempted by a higher-priority process, or it calls 

sched_yield. 

SCHEDJR: ROUND-ROBIN SCHEDULING 

sched_rr isasimpleenhancement of sched_fifo. Everything described in the precedi ngsection for sched_fifo also appliesto 
sched_rr, except that each process isonly allowed to run for a maximum time quantum. If a sched_rr process hasbeen 
runningfor a ti me peri od equal to or longer than the ti me quantum, it will beput at the end of the list for its priority. A 
sched_rr process that hasbeen preempted by a higher-priority process and subsequently resumesexecution asa running 
process will complete the unexpired portion of itsround-robin timequantum. Thelength of the ti me quantum can be 

retrieved by sched_rr_get_interval. 

SCHED OTHER: DEFAULT LINUX TIME-SHARING SCHEDULING 

sched_other can only beused at stati c priority 0. sched_other is the standard Linux ti me-sharingscheduler that isintended 
for ali processes that do not requirespecial static-priority real-timemechanisms. The process to run ischosen from the stati c 
priority 0 list based on a dynamic priority that is determi ned only inside this list. The dynamic priority is based on thenice 
level (set by thenice or setpriority system cali) and isincreased for each timequantum the process i s ready to run but is 
denied to run by thescheduler. Thisensuresfairprogressamongall sched_other processes. 

RESPONSETIME 

A blocked high-priority process wai ti ng for the I/O has a certain response time before it is scheduled again. The devi ce driver 
writer can greatly reduce this response time by usingaslow i nterrupt interrupt handler, as described in request irq(9). 

MISCELLANEO US 

Child processes inherit the scheduli ng algorithm and parameters acrossatork. 

M emory locking is usuai ly needed for real-ti me processes to avoid pagi ng del ays; this can bedonewith miock or miockaii. 

Becausea non-blocking endless loop in a processscheduled under sched_fifo or sched_rr will block ali processes with lower 
priority forever, a software developer should alwayskeep availableon the console a shell scheduled under a higher stati c 
priority than thetested application. This will allow an emergency kill of tested real-ti me appi ications that do not block or 
terminate as expected. Because sched_fifo and sched_rr processes can preempt other processes forever, only root processes 
are allowed to activate these policies under Linux. 

POSIX Systemson which sched_setscheduler and sched_getscheduler areavailabledefine_POSIX_PRIORITY_SCHEDULING in 
<unistd . h>. 

RETURN VALUE 

On success, scned_setscheduier returnso. 0 n success, sched_getscneduier returns the policy for the process (a non-negative 
integer). On error, -1 isreturned, and ermo is set appropriately. 

ERRORS 

esrch The process whoselD ispi d could not befound. 

eperm The cali ing process does not have appropriate pri vi leges. Only root processes are allowed to activate 

the sched_fifo and sched_rr policies. The process cali ing sched_setscneduier needsan effective 
UID equal to the EU ID orUID of the processi denti fi ed by pi d, or it must bea superuser process. 

einval Thescheduling policy isnot oneof therecognized policies, ortheparameter p does not makesense 

for the policy. 

STANDARD S 

POSIX.lb(formerlyPOSIX.4) 



sdect, FD CLR, FDJSSET, FDSET, FD ZERO 




BUGS 

Asof Linux 1.3.81, sched_rr has not yet been tested carefully and might not behaveexactly asdescribed or required by 
POSIX.lb. 

SEEALSO 

sched_setparam(2), sched_getparam(2), sched jield(2), sched_get_priority_max(2), sched_get_priority_min(2), nice(2), 
setpriority(2), getpriority(2), mlockall(2), munlockall(2), mlock(2), munlock(2). 

ProgrammingfortheReal World- POSIX.4 by Bill 0. G al Imeister, 0 'Reil ly & Associates, Inc., ISBN 1-56592-074-0 
I E E E Std 1003.1b-1003 (POSIX.lb standard) 

ISO/IEC 9945-1:1996— This isthe new 1996 revision of POSIX.l, which contai ns in one single standard PO SIX. 1(1990), 
POSIX.lb(1993), POSIX.lc(1995), and PO SIX .li (1995). 

Linux 1.3.81, 10 Aprii 1996 

schedjield 

schedjieid—Yields the processor 
SYNOPSIS 

#include <sched.h> 
int sched_yield(void) ; 

DESCRIPTION 

A processcan relinquish the processor voluntarily without blocking by calli ng sched_yieid. Theprocesswill then bemoved 
to the end of thequeuefor i ts stati c priority and a new processgetsto run. 

N ote: If thecurrent process istheonly process in thehighest priority list at that ti me, thisprocesswill conti nueto run after a 
cali to sched_yield. 

POSIX systems on which sched_yieid isavailabledefine_Posix_PRioRiTY_scHEDULiNG in <unìstd.h>. 
RETURN VALUE 

On success, sched_yieid returns 0. 0 n errar, -1 isreturned, and ermo issetappropriately. 

STANDARD S 

POSIX.lb (formerly POSIX.4) 

SEEALSO 

sched_setscheduier(2) for a descri ption of Li nux scheduli ng 

ProgrammingfortheReal World- POSIX.4 by Bill 0. G al Imeister, 0 'Reil ly & Associates, Inc., ISBN 1-56592-074-0 
I E E E Std 1003.1b-1993 (POSIX.lb standard) 
ISO/IEC 9945-1:1996 

Linux 1.3.81, 10 Aprii 1996 

select, FD_CLR, FDJSSET, FD_SET, FDJERO 

seiect, fd_clr, fd_isset, fd_set, fd_zero— Synchronous I/O multiplexing 
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SYNOPSIS 

(finclude <sys/time.h> 
#include <sys/types.h> 
#include <unistd.h> 

int select(int n,fd_set *r eadf ds ,fd_set *wri t ef ds ,fd_set *exceptfds, 

struct timeval "timeout); 
FD_CLR(int fd,fd_set *set ); 
FD_ISSET(int fd,fd_set *set); 
FD_SET(int fd,fd_set *set ); 
FD_ZERO(fd_set *s e t ) 



DESCRIVO N 

seiect waits for a number of fi le descriptorsto change status. 

Threeindependent setsof descriptorsarewatched. Thoselisted in readf ds will bewatched to seeif characters become 
available for reading, thosein uri t ef ds will bewatched to seeif it isokay to immediately writeon them, and thosein 
eueptf ds will bewatched for exceptions. On exit, the sets are modified in placete indicate which descriptors actually 
changed status. 

Four macrosareprovided to manipulate the sets. fd zero will clear a set. fd_set and fd_clr add or remove a given descriptor 
from a set. fdjsset teststo seeif a descriptor ispart of theset; thisisuseful after seiect returns. 

n isthehighest-numbered descriptor in any of thethree sets, plus 1. 

ti meo ut isan upper bound on theamount of timeelapsed before seiect returns It may beo, which causes seiect to return 
immediately. If timeout ìsnull (no timeout), seiect can block indefiniteiy. 

RETURN VALUE 

On success, seiect returnsthenumberof descriptors contained in the descriptor sets, which may bea if thetimeout expires 
before anything i nteresti ng happens. On errar, -1 isreturned, and ermo isset ap propri atei y; the sets and t meout become 
undefined, so do not rely on their contents after an errar. 

ERRORS 

ebadf An invalid file descri ptor was given in oneof thesets. 

eintr A non-blocked signal wascaught. 

einval n is negative. 

enomem seiect was unable to al locate memory for i nternal tables. 

NOTES 

Some code calls seiect with ali th ree sets empty, n=0, and a non-nuli timeout; thisisafairly portableway to sleep with 
subsecond preci sion. 

On Linux, t i meo ut is modified to reflect theamount of ti me not slept; most other implementationsdo not do this. This 
causes problemsboth when Linux code that readst i meout isported to other operati ngsystems and when codeis ported to 
Linux that reuses a struct timevai for multiple seiectsin a loop without reinitializing it. Considera meout to beundefined 
after seiect returns. 

EXAMPLE 

#include <stdio.h> 

#include <sys/time.h> 

#include <sys/types.h> 

#include <unistd.h> 
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int 

main(void) 
{ 

fd_set rfds; 
struct timeval tv; 
int retval; 

/* Watch stdin (fd 0) to see when it has input. */ 

FD_ZERO(&rfds) ; 

FD_SET(0, &rfds); 

/* Wait up to five seconds. */ 

tv.tv_sec = 5; 

tv.tv_usec = 0; 

retval = select(1, &rfds, NULL, NULL, &tv); 
/* Don't rely on the value of tv now! */ 

if (retval) 

printf ("Data is available now.nn"); 
/* FD_ISSET(0, &rfds) will be true. */ 

else 

printf("No data within five seconds . nn" ) ; 
exit(0) ; 

} 

SEEALSO 

accept(2), connect(2), read(2), recv(2), send(2), write(2) 

Linux 1.2, 11 February 1996 

semctl 

semcti— Samaphore-control operations 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/sem.h> 

int semctl ( int semi d, int semnun,int cmd, union semun arg ); 

DESCRIPTION 

Thefunction performs the control operation specified by cmd on the san ap ho re set (or on thes unun-nth semaphoreof the 
set) identified by semi d. The first semaphoreof the set isindicated by a value of 0 forse mun. 

Thetypeofarg istheunion 

union semun { 

int vai; /* used for SETVAL only */ 

struct semid^ds *buf; /* for IPC_STAT and IPC_SET */ 

ushort *array; /* used for GETALL and SETALL */ 

>; 

Legai valuesforcmd are 

ipcstat Copies info from thesemaphoreset data structure into the structure pointed to by erg .buf. The 

argument semnum isignored. The calli ng process must haveread access privilegeson thesemaphoreset. 
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ipc_set Writesthevaluesof some membersof the semidjs strutture pointed to byarg.buf to thesemaphore 

set data structure, updatingalso its sem_ctime member. Considered membersfrom theuser-supplied 
struct semid_ds pointed to by arg. buf are 

sem_perm.uid 
sem_perm.gid 

semjerm.mode /* only lowest 9-bits */ 

T he cali ing process'seffectiveuser ID must be super-user, creator, or owner of thesemaphore set. The 
argument semnum isignored. 

ipc_rmid Removes thesemaphore set and i ts data structuresim medi atei y, awakening ali waiting processes(with 

an errar return and errno set to EID RM ). The calling process'seffectiveuser ID must be super-user, 

creator, or owner of thesemaphore set. The argument semnum isignored. 
getall Returnssemvai for ali semaphoresof the set into arg .array. The argument semnum isignored. The 

calling processmust haveread access privilegeson thesemaphore set. 
getncnt Thesystem cali returnsthevalueof semncnt forthesemno-th semaphoreof theset (that is, thenumber 

of processes waiting for an increaseof semvai forthesemno-th semaphoreof theset). The calling 

process must have read access privi leges on the semaphoreset. 
getpid Thesystem cali returnsthevalueof sempid forthesemno-th semaphoreof theset (that is, thepid of the 

process that executed thelast semop cali forthesemno-th semaphoreof theset). The calling process 

must haveread access privilegeson the semaphoreset. 
getval Thesystem cali returnsthevalueof semvai forthesemno-th semaphoreof theset. The calling process 

must haveread access privilegeson the semaphoreset. 
getzcnt Thesystem cali returnsthevalueof semzcnt forthesemno-th semaphoreof theset (that is, thenumber 

of processes waiting for thesenwai of thesemno-th semaphoreof the setto becomeO). The calling 

process must have read access privileges on the semaphoreset. 
setall Sets semvai for ali semaphores of the set usi ng a r g . array, updati ng also the sem_ctime member of the 

semid_ds structure associated with theset. U ndo entri es are cleared for altered semaphores in ali 

processes. Processes sleepingonthewaitqueue are awakened ifsomesemvai becomesaorincreases. 

The argument semnum isignored. The calling processmust have alter access privilegeson thesemaphore 

set. 

SETVAL SetS the valueof semvai tO arg . vai for the s e mn u m-th Semaphore Of the set, updatingalso the sem_ctime 

member of thesemid_ds structure associated to theset. The undo entry is cleared for the altered 
semaphore in ali processes. Processes sleeping on thewait queue are awakened if semvai becomesG or 
increases. The calling process must have alter access privilegeson the semaphore set. 

RETURN VALUE 

On fail, thesystem cali returns -1, with ermo indicatingtheerror. Otherwise the system cali returnsa non-negative value, 
depending on cmd, asfollows: 



GETNCNT Thevalueof semncnt. 

getpid Thevalueof sempid. 

GETVAL Thevalueof semvai. 

GETZCNT Thevalueof semzcnt. 

ERRORS 

Forafailing return, ermo will be setto oneof thefollowing values: 

eaccess The cali ing process hasno access permissions needed to executecmd. 

efault Theaddress pointed to by arg .buf or arg .array i sn 't accessi bl e. 

eidrm Thesemaphoresetwasremoved. 

einval Invalid valueforcmd or s e mi d . 
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eperm Theargumentcmd has the valueiPc_SET or ipc_rmid, but the calli ng process'seffective user ID has 

i nsuffi cient privileges to executethecommand. 
erange Theargumentcmd hasthevaluesETALL or setval, and thevalueto which semvai hasto beset (forsome 

semaphoreof the set) islessthan 0 orgreaterthan theimplementation valuesEinvinx. 

NOTES 

TheiPC_iNFo, sem_stat, and sem_info control callsareused by theipcs(l) program to provide information on allocateci 
resources. In thefuturethesecan bemodified asneeded or moved to aprocfilesystem interface. 

Thefollowing system limiton semaphoresetsaffectsasemcti cali: 

semvmx M aximum valuefor semvai; implementation dependent (32767). 

SEEALSO 

ipc(5), shmget(2), shmat(2), shmdt(2) 

Linux 0.99.13, 1 N ovember 1993 



semget 

semget— Gets a semaphore set identifier 
SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/sem.h> 

int semget ( key_t k e y , int nsems, int semflg ); 

D ESC RIPTIO N 

Thisfunction returns the semaphore set identifier associated with thevalueof theargument key. A new set of nsems 
semaphoresiscreated if key hasthevalueiPC_PRivATE or key isn't ipc_private, if no existing messagequeueis associated to 
key, and if ipc_creat isasserted in semf i g (that is, semtig& ipc_creat isn't 0). The presence in semf i g of the fields ipc_creat 
and ipc_excl playsthesamerole, with respectto the existenceof the semaphore set, asthepresenceof o_creat and o_excl in 
the mode argument of theopen(2) system cali— that is, themsgget function failsif semf i g asserts both ipc_creat and ipc_excl 
and a semaphore set al ready existsfor key . 

U pon creati on, thelower 9 bitsof theargument semf i g define the access permissions(for owner, group, and others) to the 
semaphore set in the same format, and with thesamemeaning, asfor the access permissionsparameter in theopen(2) or 
creat(2) system cali (although the execute perni issions are not used by the system, and theterm write permissions, for a 
semaphore set, effectively means alter permissions). 

Furthermore, whi le creati ng, the system cali initializes the system semaphore set data structure semid_ds asfollows: 

■ sem_perm.cuid and sem_perm.uid are set to the effective user I D of the calling process. 

■ sem_perm.cgid and sem_perm.gid are set to the effective group ID of the cali i ng process. 

■ Thelowest-order9 bitsof sem_pe™. mode are setto the lowest-order 9 bitsof semf i g. 

■ semjisems isset tO the value Of ns ems . 

■ sem_otime ÌSSet tO 0. 

■ sem_ctime issetto thecurrenttime. 

Theargument nsems can beO (a"don't care") when the system cali isn't create(2). Otherwise, nsems must begreater than 0 
and less or equal to the maximum number of semaphores per semid (semmsl). 

If the semaphore set al ready exists, the access permissions are verifi ed, and a check ismadeto seeif it ismarked for destruc- 
tion. 
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RETURN VALUE 

If successful, the return valuewill be the semaphore set identifier (a positive integer); otherwiseitwill be-1, with ermo 
indicating theerror. 

ERRORS 

Forafailing return, ermo will be setto oneof thefollowing values: 

eacces A semaphore set exists for key, but the cai li ng process has no access permissionsto the set. 

eexist A semaphore set exists forkey, and semf i g wasasserting both ipc_creat and ipc_excl. 

eidrm The semaphore set ismarked to bedeleted. 

enoent N o semaphore set exists for key, and semfig wasn't asserting ipc_creat. 

enomem A semaphore set has to be created, but the system does not have enough memory for the new data 

structure. 

enospc A semaphore set has to be created, but the system li mit for the maximum number of semaphore 

sets (semmni) or the system-wide maximum number of semaphores (semmns) would beexceeded. 

NOTES 

ipc_private isn't a flagri eld but a key_t type. If this special valueisused forkey, the system cali ignoreseverything but the 
lowest-order 9 bitsof semf i g and createsa new semaphore set (on success). 

T he followi ngs are limite on semaphore set resources affecting a semget cali: 
semmni System-wide maximum number of semaphore sets; policy dependent. 

semmsl M aximum number of semaphores per semid; implementation dependent (500 currently). 

semmns System-wide maximum number of semaphores; policy dependent. A valuegreaterthan 

semmslxsemmni makes it irrelevant. 

BUGS 

Useof ipc_private doesn't inhibit other processes' access to theallocated semaphore set. 

Asforthefiles, there is currently no intrinsic way for a process to ensure excl usi ve access to a semaphore set. Asserting both 
ipc_creat and ipc_excl in semf i g only ensures (on success) that a new semaphore set will be created; it doesn't imply 
exclusi ve access to the semaphore set. 

The data structure associ ated with each semaphore in the set isn't initialized by the system cali. In order to initializethose 
data structures, you haveto execute a subsequent cali to semcti(2) to perform a setval or a setall command on the 
semaphore set. 

SEEALSO 

ftok(3), ipc(5), semctl(2), semop(2) 

Linux 0.99.13, 1 Novemberl993 

semop 

semop— Semaphore operati ons 
SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/sem.h> 

int semop ( int semid,struct sembuf *sops, unsigned nsops ); 
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DESCRIVO N 

Thefunction performsoperationson selected membersof thesemaphoreset indicated bysemi d. Each of thens ops elements 
in thearray pointed to by s ops specifiesan operation to beperformed on asemaphoreby astruct sembuf including the 
following members: 

short sem_num; /* semaphore number: 0 = first */ 
short sem_op; /* semaphore operation */ 
short sem_f lg ; /* operation flags */ 

Flags recognized in sem_fig are ipc_nowait and semjjndo. If an operation asserts sem jjndo, it will beundonewhen theprocess 
exits 

Thesystem cali semantic assures that the operations will beperformed if and only if ali ofthemwill succeed. Each operation 
isperformed on thesem_num-th semaphore of thesemaphoreset, where the first semaphore of the set issemaphoreO and is 
oneof thefollowing th ree 

■ If sem_op is a positive integer, theoperation addsthisvalueto semvai. Furthermore, if semjjndo isasserted forthis 
operation, thesystem updatestheprocessundo count forthis semaphore. Theoperation alwaysgoesthrough, so no 
processsleeping can happen. T he calli ng process must have alter permissionson thesemaphoreset. 

■ If sem op is 0, the process must haveread access permissionson thesemaphoreset. If semvai is 0, theoperation goes 
through. Otherwise, if ipc_nowait isasserted in semjig, thesystem cali fails (undoing ali previousactionsperformed), 
with ermo setto eagain. Otherwise, semzcnt is i ncremented by 1, and the process sleeps unti I oneof thefollowing 
occurs: 

■ semvai becomeso, at which timethevalueof semzcnt isdecremented. 

■ Thesemaphoreset isremoved, causi ng thesystem cali to fail with ermo setto eidrm. 

■ Thecalling process receives a signal that hasto becaught; which causesthevalueof semzcnt to bedecremented and 
thesystem cali to fail with e rrno Set tO EINTR. 

■ If sem_op islessthan 0, theprocess must have alter permissionson thesemaphoreset. If semvai isgreaterthan or equal to 
theabsolutevalueof sem_op, theabsolutevalueof sem_op issubtracted by semvai. Furthermore, if semjjndo isasserted for 
this operation, thesystem updatestheprocessundo count forthis semaphore. Then theoperation goes through. 
Otherwise, if ipc_nowait isasserted in sem_fig, thesystem cali fails (undoing ali previousactions performed), with ermo 
setto eagain. Otherwise, semncnt is incremented by 1 and the process sleeps unti I oneof thefollowing occurs: 

■ semvai becomes greater than or equal to theabsolutevalueof sem_op, at which timethevalueof semncnt is 
decremented, theabsolutevalueof sem_op issubtracted from semvai and, if semjjndo isasserted for this operation, 
thesystem updatestheprocessundo count for this semaphore. 

■ Thesemaphoreset isremoved from thesystem: thesystem cali fails, with ermo setto eidrm. 

■ Thecalling process receives a signal that hasto becaught; thevalueof semncnt isdecremented, and thesystem cali 
fails with ermo Set tO EINTR. 

In case of success, the sempid memberof the structure sem for each semaphore specified in thearray pointed to bysops isset 
to theprocessID of thecalling process. Furthermore both sem_otime and sem_ctime are setto thecurrenttima 

RETURN VALUE 

If successful, thesystem cali returnso; otherwise, it returns -1, with ermo indicating the errar. 
ERRORS 

For afailing return, ermo will be setto oneof thefollowing values: 

e2big Theargumentnsops isgreaterthan semopm, the maximum number of operationsallowed per system 

cali. 

eacces Thecalling process has no access permissionson thesemaphoreset as required by oneof the specified 

operations. 

eagain An operation could not go through, and ipcjjowait was asserted in itssemj i g . 

efault Theaddress pointed to bysops isn't accessi bl e. 
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efbig Forsomeoperation, the value ofsemjium islessthan 0 orgreater than or equal to thenumber of 

semaphoresin the set. 
eidrm Thesemaphoresetwasremoved. 

eintr Sleepingon await queue, theprocessreceived a signal that had to becaught. 

einval Thesemaphoreset doesn't exist, orsemi d islessthan 0, or nsops has a non-positive value. 

enomem Thesem_fig of some operati on asserted semjjndo, and the system does not haveenough memory to 

allocate theundo structure. 

erange Forsomeoperation, semop-teemvaiis isgreaterthan semvmx, theimplementation-dependent maximum 

value for semval. 

NOTES 

Thesem_undo structuresof a process aren't inherited by itschild on execution of afork(2) system cali. They areinstead 
inherited by the substituting process resultingfrom theexecution of theexec(2) system cali. 

Thefollowing are limitson semaphoreset resourcesaffecting asemop cali: 

semopm Maximum num ber of operati ons al lowed for onesemop cali; policy dependent. 

semvmx M aximum allowable value for semvai; implementation dependent (32767). 

Theimplementation has no intrinsic limits for theadjust on exit maximum value (semaem), the system-wi de maximum 
number of undo structures (semmnu), or the per-process maximum number of undo entri es system parameters. 

BUGS 

The system maintains a per-process sem_undo structure for each semaphorealtered by the process with undo requests. Those 
structures are free at process exit. 0 ne major cause for unhappiness with the undo mechanism is that it does not fit i n with 
thenotion of having an atomi c set of operati ons in an array of semaphores. Theundo requests for an array and each 
semaphoretherein mighthavebeen accumulated over many semopt calls. Should the process sleep when exiting, orshould ali 
undo operations be applied with the ipc_nowait flag in effect? Currently those undo operati ons that go through immediately 
areapplied, and those that require await areignored silently. Thereforeharmlessundo usageisguaranteed with private 
semaphores only. 

SEEALSO 

ipc(5), semctl(2), semget(2) 

Linux 0.99.13, 1 N ovember 1993 



send, sendto, sendmsg 

send, sendto, sendmsg— Sends a message from a socket 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/socket.h> 

int send(int s, const void *msg,int I e n , unsigned int flags); 
int sendto(int s, const void *msg, int leu, unsigned int flags, 

const struct sockaddr *to, int tolen); 
int sendmsg(int s, const struct msghdr *msg , unsigned int flags); 

DESCRIPTION 

Warning: Thisisa BSD man page. As of Linux 0.99.11, sendmsg was not implemented. 

send, sendto, and sendmsg areused to transmit a message to another socket. send may beused only when the socket isin a 
connected state, whereas sendto and sendmsg may be used at any time. 



setfsgid 



T he addressof the target isgiven by to, with t o i e n specifying itssize. Thelength of themessageisgiven by i e n . I f the 
messageistoo long to pass atomically through theunderlying protocol, the errar emsgsize isreturned, and themessageisnot 
transmitted. 

No indication of fai Iure to deli ver isimplicit in a send. Locally detected errors are indicateci by a return valueof -1. 

If no message space isavailableat the socketto hold themessageto be transmitted, send normally blocks, unlessthesocket 
hasbeen placed in non-blocking I/O mode. The seiect(2) cali may beused to determi ne when it is possi bleto send more 
data. 

Thefi ags parameter may include oneor more of the following: 

#define MSG_0OB 0x1 /* process out-of-band data */ 

#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ 

Theflag msg_oob isused to send out-of-band dataon sockets that support this notion (forexample, sock_stream); the 
underlying protocol must also support out-of-band data. msg_dontroute isusually used only by diagnostic or routing 
programs 

See recv(2) for adescription of themsgndr structure 
RETURN VALUES 

The cali returnsthenumberof characters sent, or -1 ifan errar occurred. 
ERRORS 

ebadf An invalid descri ptor was specified. 

enotsock Thearguments isnotasocket. 

efault An invaliduserspaceaddresswasspecifiedforaparameter. 

emsgsize Thesocket requiresthat message be sent atomically, and the sizeof themessageto besent made 

this i mpossi ble. 

ewouldblock Thesocket is marked non-blocking, and therequested operati on would block. 

enobufs The system wasunableto allocate an internai buffer. The operation might succeed when buffers 

becomeavailable. 

enobufs The output queuefor a network i nterface was full. This generally indicates that the interface has 

stopped sending, but it might becaused by transient congestion. 

HI STORY 

Thesefunction callsappeared in BSD 4.2. 
SEE ALSO 

fcntl(2), recv(2), select(2), getsockopt(2), socket(2), write(2) 

BSD Man Page, 24 July 1993 



setfsgid 

setfsgid— Sets group i denti ty used for fi lesystem checks 
SYNOPSIS 

int setfsgid (uid_t f sgi d ) ; 

DESCRIVO N 

setfsgid setsthegroup ID that the Linux kernel usesto check for ali accessesto the fi lesystem. N ormally, the valueof f sgi d 
will shadow the valueof the effetti ve group ID . In fact, whenever the effetti ve group ID ischanged, f sgi d wi II also be 
changed to the new value of the effecti ve group I D . 
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An explicitcall to setfsgid isusually only used by programssuch as the Linux N FS server that need to changewhat group 
ID isused forti le access without a correspondingchange in thereal and effecti ve group IDs. A changein thenormal group 
I D s for a program such astheN FS server isasecurity holethat can expose itto unwanted signalsfrom other group IDs. 

setfsgid will succeed only if the Caller isthesuperuseror if fsgi d matcheseither thereal group ID, effective group ID, saved 
group ID, orthecurrent valueof f sg d. 

RETURN VALUE 

On success, the previous valueof fsgi d isreturned. On error, thecurrent valueof fsgi d isreturned. 

C0NF0RMST0 

setfsgid is Linux speci fi c. 

BUGS 

N o error messagesof any kind arereturned to the Caller. Atthevery least, eperm should bereturned when the cali fails. 
SEEALSO 

setf suid(2) 

Linux 1.3.15, 6 August 1995 

setfsuid 

setf suid— Sets user identity used for fi lesy sterri checks 
SYNOPSIS 

int setf suid (uid_t f s ni d ) ; 

DESCRIPTION 

setfsuid sets the user ID that the Linux kernel usesto check for ali accessesto thefilesystem. N ormai ly, the valueof f sui d 
will shadow the valueof the effective user ID . In fact, whenever the effective user ID ischanged, f sui d will also bechanged 
to the new value of the effective user I D . 

An explicitcall to setfsuid isusually used only by programssuch as the Linux N FS server that need to changewhat user ID 
isused for fi le access without acorresponding changein thereal and effective user IDs. A changein thenormal user ID sfora 
program such astheN FS server isasecurity holethat can expose itto unwanted signalsfrom other user IDs. 

setfsuid will succeed only if the cai ler isthesuperuseror if fsu d matcheseither thereal user ID, effective user I D , saved user 
I D , or the current value of f s u i d . 

RETURN VALUE 

On success, the previous valueof f su d isreturned. On error, thecurrent valueof f sui d isreturned. 

C0NF0RMST0 

setfsuid is Linux specific. 

BUGS 

N o error messagesof any kind arereturned to the Caller. Atthevery least, eperm should bereturned when the cali fails. 
SEEALSO 

setf sgid(2) 

Linux 1.3.15, 6 August 1995 
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setgid 

setgid— Setsgroup identity 
SYNOPSIS 

#include <unistd.h> 
int setgid(gid_t gi d ) ; 

DESCRIPTION 

setgid sets the effecti ve group ID of thecurrent process. If the Caller isthesuperuser, thereal and saved group I D s are also 
set. 

U rider Linux, setgid isimplemented like sysv, with saved_ids. Thisallowsa setgid (other than root) program to drop ali ite 
group privi leges, do someunprivileged work, and then re-engage the originai effecti ve group ID in asecuremanner. 

If the user isroot or the program is setgid root, special care must betaken. The setgid function eh ecks the effecti ve gid of 
the Caller and, if it isthat of thesuperuser, ali process- rei ated group I D s are set to gi d. After thishasoccurred, it isimpossible 
for the program to regain root privileges. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriateJy. 
ERRORS 

eperm The user isnot thesuperuser, and gi d does not match the effecti ve or saved group ID of the calling process. 

CONFO RMSTO 

System V 

SEE ALSO 

getgid(2), setregid(2), setegid(2) 

Linux 1.1.36, 29 July 1994 

setpgid, getpgid, setpgrp, getpgrp 

setpgid, getpgid, setpgrp, getpgrp— SetS/getS process group 

SYNOPSIS 

#include <unistd.h> 

int setpgid (pid_t pid, pid_t pgid); 

pid_t getpgid(pid_t pid); 

int setpgrp(void) ; 

pid_t getpgrp(void) ; 

DESCRIPTION 

setpgid sete the process group ID of the process speci fi ed by pi d to pgi t. If pi d isO, the process ID of thecurrent process is 
used. If pgi d isO, the process ID of the process specified by pi d isused. 

getpgid returns the process group ID of the process specified by pi d. If pi d isO, theprocessID of thecurrent process isused. 
In the Linux D LL 4.4.1 library, setpgrp simply calissetpgid(0,0). 

getpgrp ÌS equivalent tO getpgid(O). 
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Processgroupsareused for distri bution of signals, and by terni in al sto arbitrate requests for their input; processes that have 
thesameprocessgroup as the terni inai areforeground and may read, whereasotherswill block with a signal if they atterri pt 
to read. 

These calls are thusused by programssuch ascsh(l) to create prò cess groupsin implementi ng job control. ThenocGPGRP 
and tiocspgrp calls described in termios(4) areused to get/set theprocessgroup of the control terminal. 

RETURN VALUE 

On success, setpgid and setpgrp return 0. 0 n errar, -1 isreturned, and ermo isset appropriately. 
getpgid returns a process group on success. On errar, -1 isreturned, and ermo isset appropriately. 
getpgrp always returns the current process group. 

ERRORS 

einval pgi d islessthan 0. 

eperm Various permission violations. 

esrch p i d does not match any process. 

C0NF0RMST0 

Thefunctions setpgid and getpgrp conform to POSIX.l. Thefunction setpgrp isfrom BSD 4.2. 1 haveno information on 
the SOurceof getpgid. 

SEEALSO 

getuid(2), setsid(2), tcsetpgrp(3), termios(4) 

Linux 1.2.4, 15 Aprii 1995 



setregid, setegid 

setregid, setegid— Setsreal and/or effecti ve group I D 
SYNOPSIS 

#include <unistd.h> 

int setregid (gid_t rgid, gid_t egid); 

int setegid(gid_t egid); 

DESCRIPTION 

setregid setsreal and effecti ve group IDsof the current process. U nprivileged usersmay changethereal group ID to the 
effecti ve group I D , and vice versa. 

Priorto Linux 1.1.38, thesaved ID paradigm, when used with setregid or setegid, wasbroken. Startingat 1.1.38, it isalso 
possi bleto set the effecti ve group ID from thesaved user ID . 

0 nly the superuser may make other changes. 

Supplying a valueof -1 for either the real or effecti ve group ID forces the system to leavethat ID unchanged. 
Currently (libc-4.x.x), setegid (e gi i ) isfunctionally equivalent to setregid (■ 1 , egid). 

If the real group ID ischanged or the effecti ve group ID isset to a valuenot equal to the previous real group ID, thesaved 
group ID will beset to thenew effecti ve group ID . 

RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned, and ermo isset appropriately. 



setreuid, seteuid 

ERRO RS 

eperm Thecurrent processisnotthesuperuser, and changesotherthan swappingtheeffectivegroup ID 

with thereal group ID , setti ngoneto thevalueof theother, or setting the effective group ID to the 
valueof thesaved group ID wasspecified. 

HI STORY 

Thesetregid function cali appeared in BSD 4.2. 
CONFO RMSTO 

BSD 4.3 

SEEALSO 

getgid(2), setgid(2) 

Linux 1.1.38, 2 August 1994 

setreuid, seteuid 

setreuid, seteuid— Sets real and / or effective user I D 
SYNOPSIS 

#include <unistd.h> 

int setreuid(uid_t ruid, uid_t euid); 

int seteuid (uid_t euid); 

DESCRIPTION 

setreuid sets real and effective user IDsof thecurrent process. U nprivileged users may change the real user ID to the 
effective user I D , and viceversa. 

Priorto Linux 1.1.37, thesaved ID paradigm, when used with setreuid or seteuid, wasbroken. 
Starti ng at 1.1.37, it isalso possibleto set the effective user ID from thesaved user ID . 
0 nly the superuser may make other changes. 

Supplyingavalueof-1 foreither the real or effective user ID forces the system to leavethat ID unchanged. 
Currently (libc-4.x.x), seteuid(eui d ) isfunctionally equivalent to setreuid(- 1 , eui d ). 

If thereal user ID ischanged or the effective user ID isset to a valuenot equal to the previous real user ID, thesaved user ID 
will be setto the new effective user ID. 

RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

eperm Thecurrent processisnotthesuperuser, and changesotherthan swapping the effective user ID 

with the real user I D , setti ng one to the value of the other, or setti ng the effective user I D to the 
valueof thesaved user ID wasspecified. 

HI STORY 

The setreuid function cali appeared in BSD 4.2. 
C0NF0RMST0 

BSD 4.3 
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SEEALSO 

getuid(2), setuid(2) 

setsid 

setsid— Createsasession and sets the process group I D 
SYNOPSIS 

#include <unistd.h> 
pid_t setsid (void) ; 



Linux 1.1.38, 2 Augii st 1994 



DESCRIVO N 

setsido createsa new session if the cai I i ng process isnot a process group leader. The calling process is the leader of thenew 
session, the process group leader of thenew process group, and hasno control lingtty. The process group ID and session ID 
of the calling process are set to the PI D of the calling process. The calling process wi II betheonly process in this new process 
group and in this new session. 

RETURN VALUE 

It returns the session ID of the calling process. 

ERRORS 

On errar, -1 will bereturned. T he only errar thatcan happen ìseperm, which isreturned when the process group I D of any 
process equals the PI D of the calling process. Thus, in particular, setsid failsif the calling process isalready a process group 
leader. 

NOTES 

A process group leader is a process with process group ID equal to itsPID . In order to besurethat setsid will succeed, fork, 
and exit, and havethechild do setsido. 

C0NF0RMST0 

POSIX 

SEEALSO 

setpgid(2), setpgrp(2) 

27 August 1994 

setuid 

setuid— Sets user identity 
SYNOPSIS 

#include <unistd.h> 
int setuid(uid_t ni ti ) ; 

DESCRIPTION 

setuid sets the effecti ve user ID of thecurrent process. If the Caller isthesuperuser, thereal and saved user I D s are also set. 
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U nder Linux, setuid isimplemented like sysv, with saved_ids. Thisallowsa setuid (other than root) program to drop ali its 
user privi leges, do someunprivileged work, and then re-engage the originai effectiveuser ID in asecuremanner. 

If the user is root or the program is setuid root, special care must betaken. The setuid function checks the effective U I D of 
the Caller, and, if it isthesuperuser, ali process-related user I D s are set to ni d . After thishasoccurred, it is i mpossible for the 
program to regain root privileges. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset ap propri atei y. 
ERRORS 

eperm Theuser isnot thesuperuser, and ui d doesnot match the effective or saved user ID of the cai li ng 

process. 

C0NF0RMST0 

System V 

SEEALSO 

getuid(2), setreuid(2), seteuid(2) 

Linux 1.1.36 29 July 1994 

setup 

setup— Setsup devicesand filesystems, mount root fi lesystem 
SYNOPSIS 

#include <unistd.h> 
syscall0(int, setup); 
int setup(void) ; 

DESCRIPTÌON 

setup iscalled oncefrom within ìinux/init/main.c. 1 1 cai I s i n iti al izati on functionsfor devicesand fi lesystem sconfigured into 
the kernel and then mountstherootfilesystem. 

N 0 user process may cali setup. Any user process, even a process with superuser permission, will receive eperm. 

RETURN VALUE 

setup always returns -1 for a user process. 

ERRORS 

eperm Always, for a user process 

CONFO RMSTO 

T his function is Linux specific. 

Linux 1.2.9, 3 May 1996 



shmctl 

shmcti— Shared memory control 



P art II: System Calls 



SYNOPSIS 

((include <sys/ipc.h> 
#include <sys/shm.h> 

int shmctl(int siimi d, int cmd, struct shmid ds *buf); 

D ESC RIPTIO N 

snmctio allows the user to receiveinformation on ashared memory segment, settheowner, group, and permissionsof a 
shared memory segment, or destroy a segment. The information about the segment identified by s h mi d isreturned in a 
s h mi d_ d s structure: 

struct shmid_ds { 

struct ipc_perm shm_perm; /* operation perms */ 
int shm_segsz; /* size of segment (bytes) */ 
time_t shm_atime; /* last attach time */ 
time_t shm_dtime; /* last detach time */ 
time_t shm_ctime; /* last change time */ 
unsigned short shm_cpid; /* pid of creator */ 
unsigned short shm_lpid; /* pid of last operator */ 
short shm_nattch; /* no. of current attaches */ 
/* the following are private */ 

unsigned short shm_npages; /* size of segment (pages) */ 
unsigned long *shm_pages; 

struct shm_desc *attaches; /* descriptors for attaches */ 

}; 

Thefieldsin the member shm_perm can beset: 

struct ipc_perm 
{ 

key_t key; 

ushort uid;/*owner euid and egid */ 
ushort gid; 

ushort cuid; /* creator euid and egid */ 
ushort egid; 

ushort mode; /* lower 9 bits of access modes */ 
ushort seq; /* sequence number */ 

>; 

T he followi ng c md s are avai lable: 

ipc_stat Used to copy the information about the shared memory segment into the buffer, b u f . The user 

must have read access to the shared memory segment. 
ipcset Used to apply the changes the user has madeto the ni d, gì d, or mode membersof the s hm_ perms 

field. Only thelowest 9 bitsof mode are used. Thes hm_ct i me member isalso updated. The user 

must betheowner, the creator, orthesuperuser. 
ipcrmid Used to mark the segment asdestroyed. 1 1 wi 1 1 actually bedestroyed after the last detach. (That is, 

when the shm_n atteri member of the associ ated structure siimi d js iszero.)Theuser must bethe 

owner, the creator, orthesuperuser. 

The user must ensure that a segment iseventually destroyed; otherwise the pages that werefaulted in will remai n in memory 
or swap. 

In additi on, thesuperuser can prevent or allow swapping of ashared memory segment with the followi ngcmds: (Linux only) 

shm_lock Prevents swapping of ashared memory segment. The user must fault in any pages that are requi rad 

to be present after locking is enabled. 
shmjjnlock Allows the shared memory segment to be swapped out. 

TheiPC_iNFo, shm_stat, and shm_info control calls are used by theipcs(l) program to provide information on allocateci 
resources. In thefuture, these may be modified as needed or moved to a proc filesystem interface. 



shmget 

SYSTEM CALLS 

fork() After atorko, thechild inherits the attached shared memory segments. 

execo After an execo, ali attached shared memory segments are detached (not destroyed). 

exito On exito, ali attached shared memory segments are detached (not destroyed). 

RETURN VALUE 

0 isreturned on success; -1 on errar. 

ERRORS 

On errar, ermo will be setto oneof thefollowing: 

eaccess Returned if ipc_stat isrequested and shm_perm.modes does not allow read access for msqid. 

efault Theargument cmd hasthevalueiPC_sET or ipc_stat, but the address poi nted to by b u f isn't 

accessi bl e. 

einval Returned if shmid isnotavalid identifier, or cmd isnotavalid command. 

eidrm Returned if shmid pointsto aremoved identifier. 

eperm Returned if ipc_set or ipc_rmid isattempted, if the user is not the creator, theowner, or the 

superuser, and if the user does not havepermission granted to hisgroup orto theworld. 

SEEALSO 

shmget(2), shmop(2) 

Linux 0.99.11, 28 Novemberl993 

shmget 

shmget— Allocates a shared memory segment 
SYNOPSIS 

#include <sys/ipc.h> 
#include <sys/shm.h> 

int shmget (key_t key.int size, int shmflg); 

DESCRIPTION 

shmget o returnsthe identifier of the shared memory segment associated with thevalueof theargument k e y. A new shared 
memory segment, with itssizeequal to theroundingup of si ze to a multi pie of page_size, iscreated if k e y hasthevalue 
ipc_private or if k e y isn't ipc_private, if no shared memory segment is associated to k e y , and if ipc_creat isasserted in 
shmfig (thatis, shmfigSi ipc_creat isn't 0). The presence in shmfig iscomposed of 

ipc_creat Createsanew segment. If thisflag isnot used, shmget o will find the segment associated with key, 

check to seeif the user has permission to receive the shmid associated with the segment, and ensure 
the segment isnotmarked fordestruction. 

ipcexcl Used with ipc_creat to ensure failureif the segment exists. 

mode_fiags (lowest9 bits) Specifiesthe permissionsgranted to the owner, group, andworld. Presently, the 

execute perm i ssi o n s are n ot used by the system . 

If a new segment iscreated, the access permissionsfrom shmfig arecopied into theshm_perm member of theshmid_ds 
structurethat defines the segment. Following istheshmid_ds structure 

struct shmid_ds { 

struct ipc_perm shm_perm; /* operation perms */ 
int shm_segsz; /* size of segment (bytes) */ 




P art II: System Calls 



time_t shm_atime; /* last attach time */ 
time_t shm_dtime; /* last detach time */ 
time_t shm_ctime; /* last change time */ 
unsigned short shm_cpid; /* pid of creator */ 
unsigned short shm_lpid; /* pid of last operator */ 
short shm_nattch; /* no. of current attaches */ 

>; 

struct ipc_perm 
{ 

key_t key; 

ushort uid; /* owner euid and egid */ 
ushort gid; 

ushort cuid; /* creator euid and egid */ 
ushort egid; 

ushort mode; /* lower 9 bits of shmflg */ 
ushort seq; /* sequence number */ 

>; 

Furthermore, while creating, thesystem cali initializes the system shared memory segment data structureshmid_ds asfollows: 

■ shm_perm.cuid and shm_perm.uid are set to the effective user I D of the calling process. 

■ shm_perm.cgid and shm_perm.gid are set to the effective group ID of thecalling process. 

■ Thelowest-order9 bits ofshm_perm. mode are setto the lowest-order 9 bit of shmfig. 

■ shm_segsz ÌS setto the valueof si ze. 

■ shm_lpid, shm_nattch, shm_atime, and shm_dtime are Set tO 0. 

■ shm_ctime issetto the current time. 

If the shared memory segment already exists, the access permissions are verified, and a check ismadeto seeif it ismarked for 
destruction. 

SYSTEM CALLS 

fork() After atorko, thechild inherits the attached shared memory segments. 

execo After an execo, ali attached shared memory segments are detached (not destroyed). 

exito On exito, ali attached shared memory segments are detached (not destroyed). 

RETURN VALUE 

A valid segment i denti fier, shmid, isreturned on success, -1 on error. 
ERRORS 

On failure, ermo issetto oneof thefollowing: 

einval Retumed if shmmin isgreaterthan si ze, if si ze isgreaterthan shmmax, or if si ze isgreaterthan the 

sizeof the segment. 

eexist Retumed if ipc_creat j iPc_ExcLwasspecified and the segment exists. 

eidrm Retumed if the segment ismarked as destroyed orwas removed. 

enospc Retumed if ali possi ble shared memory IDshavebeen taken (shmmni) or if allocati ng a segment of 

therequested sizewould cause the system to exceed thesystem-widelimiton shared memory 
(shmall). 

enoent Retumed if no segment exists for thegiven key , and ipc_creat was not specified. 

eacces Retumed if the user doesnot havepermission to access the shared memory segment. 

enomem Retumed if no memory could be allocateci for segment overhead. 
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NOTES 

ipc private isn't a flag fi eld but a key_t type. If this special valueisused for key , the system cali ignoreseverything but the 
lowest order 9 bitsof shmf i g and createsa new shared memory segment (on success). 

Thefollowing are limits on shared memory segment resourcesaffectingashmget cali: 
shmall System-wide maximum of shared memory pages; policy dependent. 

shmmax M aximum size in bytes, for a shared memory segment; implementation dependent (currently 

4MB). 

shmmin M inimum size in bytes, for a shared memory segment; implementation dependent (currently 1 

byte, although page_size istheeffective minimum size). 
shmmni System-wide maximum numberof shared memory segments; implementation dependent (currently 

4096). 

The implementation hasno specific li mi ts for the per-process maximum number of shared memory segments (shmseg). 
BUGS 

Useof ipc_private does not inhibit other processes' access to theallocated shared memory segment. 

Asforthefiles, there is currently no intrinsic way for a processto ensure excl usi ve access to a shared memory segment. 
Asserti ng both ipc_creat and ipcjxcl in shmf i g only ensures(on success) thata new shared memory segment wi II be 
created; it doesn't imply exclusi ve access to the segment. 

SEEALSO 

ftok(3), ipc(5), shmctl(2), shmat(2), shmdt(2) 

Linux 0.99.11, 28 N ovember 1993 
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shmop— Shared memory operations 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/shm.h> 

char *shmat ( int s h mi d , char *s h ma d d r , int s h rmf I g ) ; 
int shmdt ( char *s h ma d d r ) ; 



DESCRIVO N 

Thefunction shmat attaches the shared memory segment identified by shmid to the data segment of the calli ng process. The 
attaching address is speci fi ed by shmaddr with one of thefollowing criteri a: 

■ If shmaddr iso, the system triesto find an unmapped region in the rangel- 1.5GB, starti ngfrom the upper valueand 
coming down from there 

■ If shmaddr isn't 0 and shm_rnd isasserted in shmfig, theattach occursat the address equal to therounding down of 
shmaddr to a multi pie of shmlba. Otherwise, shmaddr must bea page-ali gned address at whi eh theattach occurs. 

If shm rdonly isasserted in shmf i g, the segment isattached for reading, and the process must haveread access permissionsto 
thesegment. Otherwise thesegment isattached for read and write, and the process must haveread and write access 
permissionsto thesegment. There is no notion of awrite-only shared memory segment. 

Thebrk valueof the calli ng process is not altered by theattach. The segment wi II automatically bedetached at process exit. 
T he same segment may beattached asaread and asa read-write segment, morethan once, in the process's address space. 
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On asuccessful shmat cali, the system updatesthemembersof thestructureshmid_ds associateci to theshared memory 
segment asfollows: 

■ shm_atime issetto thecurrenttime. 

■ shmjpid issetto the processi D of the calling process. 

■ shm_nattch isincremented by 1. 

N otethat theattachmentwill al so succeed if theshared memory segment is marked to bedeleted. 

Thefunction shmdt detachesfrom the calling process's data segment theshared memory segment located at theaddress 
speci fi ed by shmaddr. Thedetaching shared memory segment must beoneamongthecurrently attached ones (to the 
process's address space) with shmaddr equal to the value returned by its attaching shat cali. 

On asuccessful shmdt cali, the system updatesthemembersof the structureshmid_ds associ ated to theshared memory 
segment asfollows: 

■ shm_dtime issetto thecurrenttime. 

■ shmipid issetto the process ID of the calling process. 

■ shm_nattch is decremented by 1. If it becomesO and the segment is marked for deletion, the segment isdeleted. 
Theoccupied region in theuser space of the calling process isunmapped. 

SYSTEM CALLS 

torko After atorko, thechild inherits the attached shared memory segments. 

execo After an execo, ali attached shared memory segments are detached (not destroyed). 

exito On exito, ali attached shared memory segments are detached (not destroyed). 

RETURN VALUE 

On afailure, both functions return -1 with ermo indicating the errar; otherwise, shmat returns the address of the attached 
shared memory segment, and shmdt returns 0. 

ERRORS 

When shmat fails, at return ermo will beset to oneof thefollowing values: 

eacces The calling process has no access permissions for the requested attachtype. 

einval Invalid sri mi d value, unaligned (that is, not page- aligned and shm rnd was not specified) or invalid 

shmaddr value, or faili ng attach atbrk. 
enomem Could notallocatememoryforthedescriptororforthepagetables. 

Thefunction shmdt can fail only if thereis no shared memory segment attached at shmaddr ; in such a case, ermo will beset to 
einval at return. 

NOTES 

On executingafork(2) system cali, thechild inherits ali the attached shared memory segments. 

Theshared memory segments attached to a process executinganexec(2) system cali will not be attached to the resulti ng 
process. 

Thefollowing isa system parameter affectingashmat system cali: 

shmlba Segments low-boundary address multiple. M ust be page aligned. For thecurrent implementati on, 

the shmbla value is page_size. 

Theimplementation has no intrinsic limitto the per-process maximum number of shared memory segments (shmseg) 
SEEALSO 

ipc(5), shmctl(2), shmget(2) 

Linux 0.99.13, 28 N ovember 1993 
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shutdown— Shutsdown part of a full-duplex connection 
SYNOPSIS 

#include <sys/socket.h> 

int shutdown(int s.int how); 

DESCRIPTION 

The shutdown cali causesall or part of a full-duplex connection on thesocket associated with s to Pe shutdown. If how ise, 
further reca ves will Pedisallowed. If how isi, further sends wi II Pedisallowed. If how is 2, further sendsand receiveswill Pe 
disallowed. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

ebadf s isnotavalid descriptor. 

enotsock s isafile, notasocket. 

enotconn Thespecified socket isnotconnected. 

HI STORY 

Thesnutdown function cali appeared in BSD 4.2. 
SEEALSO 

connect(2), socket(2) 

BSD Man Page, 24 July 1993 



sigaction, sigprocmask, sigpending, sigsuspend 

sigaction, sigprocmask, sigpending, sigsuspend— PO SIX Signal-handli ng functions. 

SYNOPSIS 

#include <signal.h> 

int sigaction(int si g n u m , const struct sigaction *act , struct sigaction *oldact); 

int sigprocmask(int how, const sigset_t *set , sigset_t *oldset); 

int sigpending(sigset_t *set); 

int sigsuspend(const sigset_t *mask); 

DESCRIPTION 

The sigaction system cali isused to change the action taken Py aprocesson receipt of aspecific signal. 
si gnum specifiesthesignal and can Peany valid signal except sigkill and sigstop. 

If act is non-nuli, thenew action for signal signum isinstalled from act . If oi d a c t is non- nuli, the previ ous action issaved in 

0 1 d a c t . 

Thesigaction structure isdefined as 

struct sigaction { 

void (*sa_handler) (int) ; 
sigset_t sa_mask; 
int sajflags; 



856 
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void (*sa_restorer) (void) ; 

} 

sa_handier specifies the action to be associateci with si gnum and can be sig_dfl for the default action, sigjgn to ignorethis 
signal, or a pointer to a signal-handli ng function. 

sa_mask givesa mask of signalsthat should beblocked during execution of the signal handler. In addition, the signal that 
triggered thehandlerwill beblocked unless the sa nodefer or sajjomask flag isused. 

sa_fiags specifies a set of flags that modify the behavi or of the signal-handli ng process. It isformed by thebitwiseO R of zero 
or more of thefollowing: 

sa_nocldstop If si gnum ìssigchld, do not recei ve notification when child processes stop (that is, when 

chi Id processes recei ve oneof sigstop, sigtstp, sigttin, orsiGirou). 

sa_oneshot or sa_resethand Restores the signal action to the default stateoncethesignal handler has been called. 

(Thisis the default behavi or of thesignai(2) system cali.) 

sa_restart Provides behavi or compati ble with BSD signal semanticsby makingcertain system calls 

restartable across si gnals. 

sa_nomask or sa_nodefer D ocs not prevent the signal from bei ng received from within itsown signal handler. 

Thesa_restorer element is obsolete and should not beused. 

Thesigprocmask cali isused to change the list of currently blocked signals. The behavior of the cali isdependent on thevalue 
of how, asfollows: 

sig_block The set of blocked signals is the union of thecurrent set and the set argument. 

sigjjnblock The signals in set areremoved from thecurrent set of blocked signals. It is legai to 

attemptto unblock a signal that isnot blocked. 
sig_setmask The set of blocked signals is set to the argument set . 

If o i d s e t is non- nuli, the previousvalueof the signal mask isstored in oi dset . 

Thesigpending cali allows the examination of pendi ng signals (thosethat havebeen raised whi le blocked). The signal mask 
of pendi ng signals isstored in set. 

Thesigsuspend cali temporarily replaces thesignal mask for the process with thatgiven by ma s k andthen suspendsthe 
process unti I a signal is received. 

RETURN VALUES 

sigaction, sigprocmask, sigpending, and sigsuspend return 0 on successand -1 on errar. 
ERRORS 

einval An invai id signal wasspecified. Thiswill also begenerated if an attempt ismadeto 

change theaction for sigkill or sigstop, which cannot be caught. 

efault act , oi dact , set, oroi dset pointsto memory that isnot a vali d part of the process 

address space 

eintr System cali was interrupted. 

NOTES 

It isnot possi ble to block sigkill or sigstop with thesigprocmask cali. Attemptsto do so wi II besilently ignored. 

Setti ng sigchld to sig_ign provides automatic reapingof child processes. 

The PO SIX spec only definessA_N0CLDST0P. U seof other sa flags is non-portable. 

The sa_resethand f I ag i s co m pati bl e w i th th e SV R 4 f I ag of th e sam e n ame. 



ggnal 

T he sa_nodefer flag is compati blewith the SV R4 flag of the samename under kernels 1.3.9 and newer. On older kernels, the 
Linux implementation will allow thereceipt of any signal, not just the oneyou are installi ng (effectively overriding any 

sajnask Setti ngs). 

The sa_resethand and sa_nodefer namesforSVR4 com pati bility are present only in library versions 3.0.9 and greater. 

sigaction can be called with a nuli second argument to query thecurrent signal handler. It can also beused to check whether 
a given signal isvalid for thecurrent machine by calli ng it with nuli second and third arguments. 

See sigsetops(3) for details on manipulating signal sets. 
C0NF0RMST0 

POSIX, SVR4 

SEE ALSO 

kill(l), kill(2), killpg(2), pause(2), raise(3), siginterrupt(3), signal(2), signal(7), sigse-tops(3), sigvec(2) 

Linux 1.3, 24 August 1995 

signal 

signai— AN SI C signal handling 
SYNOPSIS 

#include <signal.h> 

void (*signal(int si g ri u m , void ( * h a n d I er ) (int) ) ) (int) ; 

D ESC RIPTIO N 

The signai system cali instai Isa new signal handler for the signal with number si gnum. The signal handler is setto handi er, 
which can bea user-specified function oroneof thefollowing: 

sig_ign Ignores the signal. 

sig_dfl Resets the signal to its default behavior. 

Theinteger argument that ishanded over to the si gnal-handling routine is the signal number. T hi smakesit possi bleto use 
onesignal handler for several signal s. 

RETURN VALUE 

signai returns the previ ous vai ueof the signal handler, or sig_err on errar. 
NOTES 

Signal handlers cannot be set for sigkill or sigstop. 

Unlikeon BSD systems, si gnals under Linux are reset totheir default behavi or when raised. However, ifyou include <bsd/ 
signai. n> instead of <signai.n>, signai isredefined as_bsd_signai, and signai hastheBSD semantics. Both versions of 
signai are library routines built on topof sigaction(2). 

If you're confused by theprototypeatthetop of thisman page, it may help to see it separated out likethis: 

typedef void (*sighandler_t) (int) ; 

sighandler_t signal(int si gnum, sighandler_t handler); 

Accordi ngto POSIX, the behavior of a processi sundefi ned after it ignores a sigfpe, sigill, or sigsegv signal thatwas not 
generated by the km o or raiseo function. Integer di vision by 0 hasundefined result. 0 n some architecturesit will 
generate a sigfpe signal. Ignoringthis signal might lead to an endless loop. 
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CONFORMSTO 

ANSI C 

SEEALSO 

kill(l), kill(2), killpg(2), pause(2), raise(3), sigaction(2), signal(7), sigsetops(3), sigvec(2), alarm(2) 

Linux 2.0, 21 July 1996 

sigblock, siggetmask, sigsetmask, sigmask 

sigblock, siggetmask, sigsetmask, sigmask— M anipulate the Signal mask 

SYNOPSIS 

#include <signal.h> 
int sigblock (int mask ) ; 
int siggetmask(void) ; 
int sigsetmask(int mask); 
int sigmask(int signum); 

DESCRIPTION 

This interface is made obsolete by sigprocmask(2). 

Thesigbiock system cali addsthesignalsspecified inmask tothesetof signals currently beingblocked from delivery. 

The sigsetmask system cali replacestheset of blocked si gnals total lywith a new set specified in mask. Signals are blocked if 
thecorrespondingbitin mask isal. 

Thecurrent set of blocked signals can beobtained usi ng siggetmask. 
Thesigmask macro isprovided to constructthemaskforagiven si gnum. 

RETURN VALUES 

siggetmask returnsthecurrent set of masked signals. 

sigsetmask and sigblock return the previous set of masked signals. 

NOTES 

Prototypesfor thesefunctionsareonly available if use_bsd isdefined before<signai.h> isincluded. 

It isnot possi bleto block sigkill or sigstop— this restri ction issilently imposed by the system. 

HISTORY 

Thesefunction callsappeared in BSD 4.3 and aredeprecated. 
SEEALSO 

kill(2), sigprocmask(2), signal(7) 

Linux 1.3, 31 August 1995 



sigpause 

sigpause— Atomically releases blocked signals and waitsfor interrupt 



si gretti rn 



SYNOPSIS 

#include <signal.h> 

int sigpause(int sigmask); 

DESCRIPTION 

This interface is made obsolete by sigsuspend(2). 

sigpause assignssi gmask to the set of masked signalsand then waitsfor asignal to arrive; on return, theset of masked signals 
isrestored. 

sigmask isusually 0 to indicate that no signalsareto beblocked. sigpause always termi natesby bei ng interrupted, returni ng 

-1 With ermo Set tO EINTR. 

HI STORY 

Thesigpause function cali appeared in BSD 4.3 and isdeprecated. 
SEEALSO 

sigsuspend(2), kill(2), sigaction(2), sigprocmask(2), sigblock(2), sigvec(2) 

Linux 1.3, 24 July 1993 

sigreturn 

sigreturn— Retumsfrom the si gnal handler and cleansup thestack frame 
SYNOPSIS 

int sigreturn(unsigned long unused); 

DESCRIPTION 

WhentheLinux kernel creates thestack frame for asignal handler, acall to sigreturn isinserted into thestack frame so that 
thesignal handler wi II cali sigreturn upon return. This inserted cali to sigreturn cleansup thestack so that the processcan 
restart from whereitwas interrupted by thesignal. 

RETURN VALUE 

sigreturn never retums. 

WARNING 

The sigreturn cali isused by the kernel to implement signal handlers. It should never becalled directly. Betteryet, the 
specific use of the unused argument varies dependi ng on the archi tecture. 

C0NF0RMST0 

sigreturn ÌS Specific tO Linux. 

FILES 

/usr/src/linux/arch/i386/ kernel /signal .c 
/ usr/src/linux/arch/alpha/ kernel/ entry .S 

SEEALSO 

kill(2), signal(2), signal(7) 

Linux 1.3.20, 21 August 1995 
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sigvec 

sigvec— BSD software si gn al faci I iti es 
SYNOPSIS 

#include <bsd/signal.h> 

int sigvec(int sig, struct sigvec *vec, struct sigvec *ovec); 

D ESC RIPTIO N 

This interface is made obsolete by sigaction(2). 

U nder Linux, sigvec is#defined to sigaction, and providesat best a rough approximation of the BSD sigvec interface. 
SEEALSO 

sigaction(2), signal(2) 

Linux 1.3 31 August 1995 

socket 

soc ket— C reates anendpointforcommuni cati o n 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/socket.h> 

int socket(int d o ma i n , intt y pe , int protocol ); 

DESCRIPTION 

socket createsan endpointfor communication and returns a descriptor. 

Thedomai n parameter specifies a communi cations domain within which communication will take place thisselectsthe 
protocol family thatshould beused. These fami lies are defi ned in the include fi le sys/socket.n.T he currently understood 
formatsare 

afjjnix U N IX internai protocols 

af_inet ARPA Internet protocols 

af_iso ISO protocols 

af_ns Xerox N etwork Systems protocols 

af_implink IM P host at IM P link layer 

The socket hastheindicated type, which specifies the semantics of communication. The currently defi ned types are 

SOCK_STREAM 

SOCK_DGRAM 

SOCK_RAW 

SOCK_SEQPACKET 

S0CK_RDM 

A sock_stream type provi des sequenced, reliable, two-way connection- based bytestreams. An out-of-band data tran smission 
mechanism may besupported. A sock_dgram socket supportsdatagrams (connectionless, unreliablemessagesof afixed, 
typically small, maximum length). A sock_seqpacket socket may providea sequenced, reliable, two-way connection- based 
data tran smission path for datagramsof fixed maximum length; a consumer might berequired to read an entire packet with 
each read system cali. This faci lity is protocol specific, and presently isimplemented only for pf_ns. sock_raw sockets provide 



socket 



access to internai network protocols and interfaces. T he types sock_raw, which isavailableonly to thesuperuser, and 
sock_rdm, which isplanned but notyet implemented, arenot described here. 

The protocol specifiesa particular protocol to beused with the socket. N ormally only a single protocol existsto support a 
parti cular socket typewithin agiven protocol family. H owever, it ispossiblethat many protocols mayexist, in which casea 
particular protocol must bespecified in thismanner. The protocol number to use is particular to the com munì cation domain 
in which communication isto take place; seeprotocois(5). 

Sockets of type sock stream arefull-duplex bytestreams, similarto pipes. A stream socket must bein aconnected state before 
any datacan besent or received on it. A connection to another socket iscreated with a connect(2) cali. Onceconnected, data 
may betransferred using read(2) and write(2) callsor somevariant of thesend(2) and recv(2) cai Is. W hen a sessi on has been 
completed, aciose(2) may be performed. Out-of-band data can also betransmitted as described in send(2) and received as 
described in recv(2). 

The Communications protocols used to implement a sock_stream ensurethat data isnot lost orduplicated. If a piece of data 
for which thepeer protocol has buffer space can not besuccessfully transmitted within a reasonablelength of time, the 
connection isconsidered broken, and callswill indicate an errorwith -1 returnsand with etimedout asthespecificcodein the 
global vari able ermo. The protocols optional ly keep sockets warm by forcing transmissions roughly every minute in the 
absenceof other activity. An error isthen indicateci if no responsecan beelicited on an otherwise i die connection fora 
extended peri od (forexample, 5 minutes). A sigpipe signal israised if aprocesssendson a broken stream; thiscausesnaive 
processes, which do not handlethe signal, to exit. 

sock_seqpacket sockets etri pi oy the same system calls assocK stream sockets. The only differenceisthat read(2) callswill 
return only the amount of data requested, and any that is remai ni ng in the arrivi ng packetwill bediscarded. 

sock_dgram and sock_raw sockets allow thesending of datagramsto correspondents named in send(2) calls. Datagramsare 
generally received with recvfrom(2), which returnsthenext datagram with its return address. 

An f cnti(2) cali can be used to specify a process group to recei ve a sigurg signal when the out-of-band data arrives. It can 
also enablenon-blocking I/O and asynchronousnotification of I/O events viasiGio. 

The operati on of sockets is controlied by socket-level options. These opti ons are defi ned in thefilesys/socket.h. 
setsockopt(2) and getsockopt(2) and areused to set and get options, respectivdy. 

RETURN VALUES 

A -1 isreturned if an error occurs; otherwise, the return value isa descriptor referencing the socket. 
ERRORS 

eprotonosupport Theprotocol type or the speci fi ed protocol isnot su pported within thisdomain. 

emfile The per-process descriptor table i s full. 

enfile Thesystem fi le table is full. 

eaccess Permission to create a socket of the speci fi ed type and/or protocol isdenied. 

enobufs Insufficient buffer space is available. Thesocket cannot be createci until sufficient resourcesare 

freed. 

HISTORY 

Thesocket function cali appeared in BSD 4.2. 
SEE ALSO 

accept(2), bind(2), connect(2), getprotoent(3), getsockname(2), getsockopt(2), ioctl(2), listen(2), read(2), recv(2), 
select(2), send(2), shutdown(2), socketpair(2), write(2) 

"An Introductory 4.3 BSD Interprocess Communication Tutori al" isreprinted in UNIX Programmer'sSupplementary 
DocumentsVolumel 

"BSD Interprocess Com munì cation Tutorial" isreprinted in U N IX Programmer'sSupplementary DocumentsVolumel 

BSD Man Page, 24 July 1993 
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socketcall 

socketcaii— Socket system calls 
SYNOPSIS 

int socketcall(int cali , unsigned long *args); 

D ESC RIPTIO N 

socketcall is a common kernel entry pointforthesocket system calls. cai i determi neswhi eh socketfunction to invoke. args 
pointsto a block contai ning the actual arguments, which arepassed through to the appropriate cali. 

User programsshould cali the appropri atefunctionsbytheir usuai names. 0 nly standard library implementorsand kernel 
hackers need to know about socketcall. 

SEEALSO 

accept(2), bind(2), connect(2), getpeername(2), getsockname(2), getsockopt(2), listen(2), recv(2), recvfrom(2), send(2), 
sendto(2), setsockopt(2), shutdown(2), socket(2), socketpair(2) 

Linux 1.2.4, 15 Aprii 1995 

socketpair 

socketpair— C reates a pair of connected sockets 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/socket.h> 

int socketpair(int d , int type, int protocol , int s»[2]); 

DESCRIPTION 

The cali createsan unnamed pair of connected sockets in the specified domain d, of th e speci fi ed type, and usi ng the 
optional ly specified protocol .Thedescriptorsused in referencingthenew sockets are returned in sv w and sv [1]. Thetwo 
sockets are i ndi sti nguishable. 

RETURN VALUE 

On success, 0 is returned. 0 n errar, -1 is returned, and ermo isset appropriately. 
ERRORS 

emfile Too many descriptors are in usebythisprocess. 

eafnosupport T he specified addressfamily isnot supported on this machine. 

eprotonosupport T he specified protocol isnot supported on thismachine 

eopnosupport T he specified protocol does not support creati on of socket pairs. 

efault Theaddresssv does not specify a valid partof the process'saddress space. 

HI STORY 

Thesocketpair function cali appeared in BSD 4.2. 



BUGS 

Thiscall iscurrently implemented only fortheU N IX domain. 



stat, fstat, Istat 
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SEEALSO 

read(2), wrìte(2), pipe(2) 

BSD Man Page 24 July 1993 



stat, fstat, lstat 

stat, fstat, istat— G et file status 
SYNOPSIS 

#include <sys/stat.h> 
#include <unistd.h> 

int stat(const char *f il e nane .struct stat *buf); 

int fstatfint f il edes , struct stat *buf ) ; 

int lstat(const chat- *f i I e _ n a me , struct stat *buf); 

DESCRIPTION 

Thesefunctions return information about the specified file. You do not need any access rightsto the fi le to get this 
information, but you need search rightsto ali directoriesnamed in thepath leadingto the fi le. 

stat stats thefilepointed to by f i i e.name and fillsin buf . 

istat i sideriti cai to stat, except that the link itself i s stateci, notthefilethat isobtained by traci ng the links. 

fstat isidentical to stat, except that the open file poi nted to by f m edes (asreturned by open(2)) i s stateci in place of 

fi I e _ n a me . 

They ali return a stat structure, which isdeclared asfollows: 

struct stat 
{ 



dev_t 




st 


dev ; 


/* device */ 


ino_t 




st 


no ; 


/* inode */ 


umode_t 




st 


mode ; 


/*protection */ 


nlink_t 




st 


n 1 i n k ; 


/* number of hard links */ 


uid_t 




st 


ui d ; 


/* user ID of owner */ 


gid_t 




st 


gi d ; 


/* group ID of owner */ 


dev_t 




st 


r dev ; 


/* device type (if inode device) */ 


off_t 




st 


s i z e ; 


/* total size, in bytes */ 


unsigned 


long 


st 


bl ks i z e ; 


/* blocksize for filesystem I/O */ 


unsigned 


long 


st 


bl oc ks ; 


/* number of blocks allocated */ 


time_t 




st 


a t i me ; 


/* time of last access */ 


time_t 




st 


mt i me ; 


/* time of last modification */ 


time_t 




st 


et i me ; 


/* time of last change */ 



}; 

N otethatstji ocks may not alwaysbein termsof blocks of si ze s t _ b ksi ze, and that st. bl k s i z e may instead providea 
notion of the"preferred" block sizefor efficient filesystem I/O. 

N ot ali the Linux fi lesystems implement ali thetimefi elds. Traditionally, st.at i me ischanged by mknod(2), utime(2), read(2), 

write(2), and truncate(2). 

Traditionally, st.mt i me ischanged by mknod(2), utime(2), and write(2). st.mt i me isnot changed for changesin owner, group, 
hard link count, or mode. 

Traditionally, st. et i me ischanged by writing or by setti ng inode information (that is, owner, group, link count, mode, and 
so on). 
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Thefollowing macrosare defined to check thefiletype: 



SISLNK(m) 

SISREG(m) 

S_ISDIR(m) 

S_ISCHR(m) 

S_ISBLK(m) 

S_ISFIFO(m) 

SISSOCK(m) 



Is it a symbolic link? 

Isitaregular file? 

Is ita directory? 

Isit acharacter device? 

Is ita block device? 

Isitfifo? 

Is it asocket? 



T hefollowing flags are defined forthest_mode fidd: 

s ifmt 00170000 Bitmaskfor thefiletype bitfields 

s ifsock 0140000 Socket 

s iflnk 0120000 Symbolic link 

s_ifreg 0100000 Regular file 

s_ifblk 0060000 Block device 

s ifdir 0040000 D irectory 

sjfchr 0020000 C haracter device 

s ififo 0010000 Fifo 

sjsuid 0004000 Set U ID bit 

s_isgid 0002000 Set G ID bit 

sjsvtx 0001000 Sticky bit 

s_irwxu 00700 User (fileowner) hasread, write, and execute perni ission 

sjrusr (s_iread) 00400 U ser has read permission 

s_iwusr (s_iwrite) 00200 User haswrite permission 

s_ixusr (s_iexec) 00100 User has execute permission 

sirwxg 00070 Group hasread, write, and execute permission 

sjrgrp 00040 Group hasread permission 

sjwgrp 00020 Group haswrite permission 

sjxgrp 00010 Group has execute permission 

s_irwxo 00007 others have read, write, and execute permission 

s_iroth 00004 Others have read permission 

s_iwoth 00002 Others havewrite permission 

sjxoth 00001 Others have execute permission 

RETURN VALUE 

On success, 0 isreturned. O n error, -1 isreturned, and ermo isset appropriately. 
ERR0RS 

f i I edes isbad. 



EBADF 
ENOENT 



Filedoesnot exist. 



C0NF0RMST0 

SVID (not istato), AT&T (notistato), POSIX (not istato), X/OPEN (not istato), BSD 4.3 
SEEALS0 

chmod(2), chown(2), readlink(2), utime(2) 

Linux 1.1.75, 1 January 1995 
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statf s, f statf s 

statfs, fstatfs— G et fi lesystem statisti cs 
SYNOPSIS 

#include <sys/vfs.h> 

int statf s(const char * p a t h , struct statfs *buf); 
int fstatfs(int fd, struct statfs *buf); 

D ESC RIPTIO N 

statfs returns informati on about a mounted fi lesystem. patii isthepathnameof any file within the mounted fi lesystem. t>uf 
is a pointer to a statfs structure defined asfollows: 

struct statfs { 



long 


f_type; 




type of filesystem (see below) */ 


long 


f_bsize; 


/ * 


optimal transfer block size */ 


long 


f_blocks; 


/ * 


total data blocks in filesystem */ 


long 


f_bf ree; 


/ * 


free blocks in fs */ 


long 


f_bavail; 


/ * 


free blocks avail to non-superuser */ 


long 


f_files; 


/ * 


total file nodes in filesystem */ 


long 


f_ff ree; 


/ * 


free file nodes in fs */ 


fsid_t 


f_fsid; 


/ * 


filesystem id */ 


long 


f_namelen; 


/ * 


maximum length of filenames */ 


long 


f_spare[6] ; 


/ * 


spare for later */ 



Filesystem types: 








linux/ext2_f s . h : 


EXT2_0LD_SUPER MAGIC 


0XEF51 




linux/ext2_f s . h : 


EXT2_SUPER_MAGIC 


0XEF53 




linux/ext_f s . h: 


EXT_SUPER_MAGIC 


0X137D 




linux/iso_fs.h: 


ISOFS_SUPER_MAGIC 


0x9660 




linux/minix_f s.h: 


MINIX_SUPER_MAGIC 


0X137F 


/* 


linux/minix_f s.h: 


MINIX_SUPER_MAGIC2 


0X138F 


/* 


linux/minix_f s.h: 


NEW_MINIX_SUPER_MAGIC 


0x2468 


/* 


linux/msdos_f s.h: 


MSDOS_SUPER_MAGIC 


0x4d44 




linux/nf s_f s . h: 


NFS_SUPER_MAGIC 


0x6969 




linux/proc_f s . h : 


PROCSUPERJIAGIC 


0x9fa0 




linux/xia_f s . h: 


XIAFS_SUPER_MAGIC 


0X012FD16D 



orig. minix */ 
30 char minix */ 
V2 */ 



Fieldsthatareundefined for a parti cui ar fi lesystem are setto -1. fstatfs returns the same informati on about an open file 
referenced by descriptor f d . 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 



For statfs: 

ENOTDIR 
EINVAL 

ENAMETOOLONG 

ENOENT 
EACCES 
ELOOP 



A componentof thepath prefixof p a t h is nota directory, 
p a t h contai ns a character with the high-order bit set. 

Thelength of a componentof patii exceeds255 characters, orthelength of patti exceeds 1,023 
characters. 

Thefilereferred to by patti does not exist. 

Search permission isdenied for a componentof thepath prefix of pat h. 

Too many symbolic linkswereencountered in translati ng pat h. 
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EFAULT 
EIO 

Fortstatfs: 

EBADF 
E FAULT 
EIO 



buf orpath pointsto an invalici address. 

An I/O errar occurredwhi le readingfrom or writi ng to thefilesystem. 

fd isnot a valid open file descri ptor. 
buf pointsto an invalid address. 

An I/O errar occurredwhi le readingfrom or writi ngto thefilesystem. 



SEEALSO 

stat(2) 



Linux 0.99.11, 24 July 1993 



stime 

stime— Set time 
SYNOPSIS 

#include <t ime . h> 
int stime(time_t *t ) ; 

D ESC RIPTIO N 

stime sets the system 's idea of the ti me and date, time, pointed to byt , is measured in secondsfrom 00:00:00 GM T January 
1, 1970. stimeo mayonly beexecuted bythesuperuser. 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 
ERR0RS 

eperm Thecaller isnotthesuperuser. 

C0NF0RMST0 

SVID,AT&T,X/OPEN 

SEEALSO 

date(l) 

Linux 0.99.11, 24 July 1993 



swapon, swapof f 

swapon, swapoff— Start/stop swapping to file/device 
SYNOPSIS 

#include <unistd.h> 
#include <linux/swap.h> 

int swapon(const char * p a t h , int swapflags); 
int swapoff (const char *path); 



symlink 




DESCRIVO N 

swapon setstheswap areato thefileor block devi ce speci fi ed by patii, swapoff stopsswappingto the file or block device 
specified by path. 

swapon takes a swapf i ags argument. If swapf i a g s has theswAP_FLAG_PREFER bit turned on, thenew swap area wi II havea higher 
prioritythan default. The priority isencoded as (prio « swap_flag_prio_shift) & swap_flag_prio_mask. Thesefunctions 
may only be used by the superuser. 

PRIORITY 

Each swap area has a priority, either high or low. The default priority islow. Within the low-priority areas, newer areasareof 
even lower priority than older areas. 

Ali prioritiessetwith swapf i ags are high priority, higher than the default. They may haveany non-negati ve valuechosen by 
thecaller. H igher numbersmean higher priority. 

Swap pagesareallocated from areas in priority order, highest priority first. For areas with different priorities, a higher- 
priority area isexhausted beforeusinga lower- priority area. If two or more areas havethesame priority, and that isthe 
highest priority available, pagesareallocated on a round-robin basisbetween them. 

Asof Linux 1.3.6, the kernel usually follows these rules, but thereareexceptions. 
RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

M any oth er erro rs besides the followi ng can occur if path isnot valid: 

eperm The user isnot the superuser, or more than max_swapfiles (defined to be 8 in Linux 1.3.6) are in 

use. 

einval Returned if patti exists, but isneither a regular path nor a block device. 

enoent Returned if patti doesnotexist. 

enomem Returned if there is i nsuffici ent memoryto start swapping. 

C0NF0RMST0 

Thesefunctions are Linux speci fic. 

NOTES 

T he partition or path must beprepared with mkswap(8). 
HI STORY 

Thesecond (swapfiags) argument was i ntroduced in Linux 1.3.2. 
SEEALSO 

mkswap(8), swapon(8), swapoff (8) 

Linux 1.3.6, 22 July 1995 



symlink 

symlink— M akes a new nameforafile 
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SYNOPSIS 

#include <unistd.h> 

int symlink(const char *ol dpath, const char *newpath); 

DESCRIPTION 

symiink createsa symbol ic link named oi dpath that containsnewpat h . 

Symbolic links are interpreted at runtime, as if the contentsof the link weresubstituted into thepath being followed to find 
a fi le or directory. 

Symbolic links may contai n . . path componentsthat (if used at the start of the link) referto the parent d i rectori es of theone 
in which the link resides. 

A symbolic link (also known as a soft link) can point to an existing file orto a nonexistent one; the latter caseisknown asa 
dangli ng link. 

Thepermissionsof a symbolic link areirrelevant; theownership isignored when following the link, but ischecked when 
removal or renaming of the link isrequested and the link is in a directory with the sticky bit set. 

If newpatti exists, itwill not be overwritten. 
RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

eperm Thefilesystem containing pat h n a me doesnotsupportthecreation of symbolic links. 

efault oi dpath or newpat h points outside your accessible address space. 

eacces Write access to the directory containing newpat h isnot allowed for the process's effective U I D , or 

oneof the di rectori es in newpat h did notallowsearch (execute) permission. 

ENAMETOOLONG o I dpath OT newpat h waStOO long. 

enoent A directory componenti n newpat h doesnot exist or is a dangli ng symbolic link, or oi dpath isthe 

empty stri ng. 

enotdir A component used asa directory in newpat h isnot, in fact, a directory. 

enomem I nsuffi ci ent kernel memory wasavailable. 

erofs Thefileison a read-only filesystem. 

eexist newpat h al ready exists. 

eloop newpat h containsa referenceto a circular symbolic link— that is, a symbolic linkwhoseexpansion 

contai ns a referenceto itself. 
enospc The device containing the fi le has no room forthenew directory entry. 

NOTES 

Nocheckingofoìdpath isdone. 

D eleti ng the namereferred to by a symiink will actually delete thefile (unless it also hasother hard links). If this behavi or is 
notdesired, use link. 

CONFO RMSTO 

SVID.AT&T, POSIX, BSD 4.3 

BUGS 

Seeopen(2) regarding multiplefileswith thesamename, and N FS. 




SEEALSO 

link(2), unlink(2), rename(2), open(2), lstat(2), ln(l), link(8) 

Linux, 24 J uly 1993 

sync 

sync— Commits buffer cache to disk 
SYNOPSIS 

#include <unistd.h> 
int sync(void) ; 

DESCRIPTION 

sync first commits inodesto buffers, and then buffersto disk. 

RETURN VALUE 

sync alwaysreturnsa. 

C0NF0RMST0 

SVID,AT&T,X/OPEN,BSD 4.3 

BUGS 

Accordi ng to the standard specification (for example, SVID), synco schedulesthewrites, but it might return beforethe 
actual writing isdone. However, sinceversion 1.3.20, Linux doesactually wait. (Thisstill doesnot guarantee data integrity; 
modem diskshavelarge caches.) 

SEEALSO 

bdflush(2), fsync(2), f datasync(2), update(8), sync(8) 

Linux 1.3.88, 15 Aprii 1995 

sysctl 

syscti— Reads/writes system parameters 
SYNOPSIS 

(finclude <unistd.h> 
#include <linux/unistd . h> 
#include <linux/sysctl.h> 

_syscall1 (int_sysct I , struct sysctl_args *args); 

int sysctl(struct sysctl_args *args); 

DESCRIPTION 

The syscti cali reads and/or writes kernel parameters— for example, thehostnameorthemaximum numberof open fi les. 
The argument has the form 

struct syscti args { 

int *name; /* integer vector describing variable */ 
int nlen; /* length of this vector */ 
void "oldval; /* 0 or address where to store old value */ 
size_t *oldlenp; /* available room for old value, 
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overwritten by actual size of old value */ 
void *newval; /* 0 or address of new value */ 
size_t newlen; /* size of new value */ 

}; 

Thiscall doesasearch in atreestructure, possi bly resembli ng a directory tree under /proc/sys, and, if therequested item is 
found, calls some appropri aterouti ne to read or modify the value 

EXAMPLE 

#include <linux/unistd . h> 
#include <linux/types.h> 
#include <linux/sysctl.h> 

_syscall1 (int, _sysctl, struct sysctl args *, args); 

int sysctl(int *name, int nlen, void *oldval, size_t "oldlenp, 
void "newval, size_t newlen) 

{ 

struct sysctl args args={name, nlen, oldval.oldlenp, newval, newlen}; 

return _sysctl(&args) ; 

} 

#define SIZE(x) sizeof (x) /sizeof (x[0] ) 
#define OSNAMESZ 100 

char osname[OSNAMESZ] ; 
int osnamelth; 

int name[] = { CTL_KERN, KERN_OSTYPE }; 

main() { 

osnamelth = SIZE(osname) ; 

if (sysctl(name, SIZE(name), osname, fkosnamelth, 0, 0)) 
perror( "sysctl" ) ; 

else 

printf ( "This machine is running %*s\n", osnamelth, osname); 
return 0; 

} 

RETURN VALUES 

Upon successful completion, syscti returnso. Otherwise, a value of -1 isreturned, and ermo issetto indicate the errar. 
ERRORS 

ENOTDIR name wasnotfound. 

eperm N o search permission foroneof theencountered directories, or no read pernii ssion whereoi dva 

was nonzero, or no write permission wherenewva was nonzero. 
efault Theinvocation asked f or the previ ous vai ue by setti ng o i eh ai non-N U LL, but allowed zero room 

in o I di e n p . 

CONFO RMSTO 

Thiscall is Linux specific. 

HISTORY 

A syscti cali hasbeen present in Linux si nce versi on 1.3.57. It ori ginated in BSD -4.4. 0 nly Linux has the /proc/sys mirrar, 
and theobject-namingschemesdiffer between Linux and BSD 4.4, but the declaration of thesyscti(2) function isthesame 
in both. 



sysinfo 




BUGS 

N ot ali available objects are properly documentai 

It isnotyet possibleto change operati ng system by writing to /proc/sys/kernei/ostype. 
SEEALSO 

proc(5) 

Linux 1.3.85, 11 Aprii 1996 

sysfs 

sysf s— Getsfilesystem type information 
SYNOPSIS 

int sysfs(int opti o n , const char * f s n a me ) ; 

int sysfs (int opt i on , unsigned int f s i ndex , char * buf ) ; 

int sysfs(int opt i on ) ; 

D ESC RIPTIO N 

sysfs returns information aboutthefilesystem types currently present in the kernel. Thespecificform of thesysfs cali and 
the information returned depend on theoption in effect. You can 

■ Translate the fi lesystem identifier string f sname i nto a fi lesystem type i ndex. 

■ Translate the fi lesystem type index fsj ndex into anull-terminated fi lesystem identifier string. T hi s string wi II bewritten 
to the buffer pointed to bybuf . M akesure that buf hasenough space to accept the string. 

■ Return the total numberof fi lesystem types currently present in the kernel. 

Thenumberingof thefilesystem typeindexesbeginswith 0. 
RETURN VALUE 

On success, sysfs returns thefilesystem i ndex for the first option, a forthesecond option, and thenumber of currently 
confi gured fi I esystem s f o r th e th i rd option. On error, -1 is returned, and ermo isset appropriately. 

ERRORS 

einval f sname isnota valid filesystem type identifier; f s _ i ndex isout of bounds; option is invai id. 

efault Eitherfsname orbuf is outside your accessible address space. 

C0NF0RMST0 

System V 

Linux 1.3.16, 9 August 1995 

sysinfo 

sysinfo— Returnsinformation on overall system stati stics 

SYNOPSIS 

Asof Linux 0.99.10 and image release4.4, 

#include <linux/kernel.h> 

#include <linux/sys.h> 

int sysinfo(struct sysinfo *info); 
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D ESC RIPTIO N 

sysinfo return s information in thefollowing structure: 

struct sysinfo { 
long uptime; 
unsigned long loads[3]; 
unsigned long totalram; 
unsigned long freeram; 
unsigned long sharedram; 
unsigned long bufferram; 
unsigned long totalswap; 
unsigned long freeswap; 
unsigned short procs; 
char _f [22] ; 

}; 

sysinfo providesasimpleway of getting overall system statistics. This is more portablethan reading /dev/kmem. 
RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

efault The pointer to s t r uct sysi nf 0 isinvalid. 

CONFO RMSTO 

Thisfunction is Linux speci fic. 

BUGS 

The Linux D LL 4.4.1 librariesdo not contai n a proper prototypefor thisfunction. 

Linux 0.99.10, 24 July 1993 

syslog 

sysiog— Reads and/or clears kernel message ring buffer; sets consoie_iogievei 
SYNOPSIS 

#include <unistd.h> 
#include <linux/unistd . h> 

_syscall3(int syslog, int t ype , char *buf p , int I en ) ; 
int syslog(int t ype , char *buf p , int I en ) ; 

DESCRIPTION 

Thisisprobably not thefunction you are i nterested in. Look atsysiog(3) fortheC library interface. This page only 
documents the bare kernel system cali interface. 

Thetype argument determines the action taken by sysiog. 

From kernel/printk.c:/* 

Valid commandsto sysiog are 
a— Closethelog. CurrentlyaNOP. 

1— Open the log. CurrentlyaNOP. 

2— Read from the log. 



/* Seconds since boot */ 

/* 1, 5, and 15 minute load averages */ 

/* Total usable main memory size */ 

/* Available memory size */ 

/* Amount of shared memory */ 

/* Memory used by buffers */ 

/* Total swap space size */ 

/* swap space stili available */ 

/* Number of current processes */ 

/* Pads structure to 64 bytes */ 




3— Read up to the last 4KB of messages in the ring buffer. 

4— Read and clear last 4KB of messages in the ring buffer. 

5— Clear ring buffer. 

6— Disableprintksto console. 

7— Enableprintksto console. 

8— Set ìevei of messages printed to console. 

Only function 3 isallowed to non-root processes. 
THE KERNEL LOG BUFFER 

The kernel hasa cyclic buffer of length log_buf_len (4096) in which messages given asargument to the kernel function 
p rint k ( ) are sto red ( regard I ess of th é r I ogl evel ) . 

The cali sysiog (2,buf ,i en ) waits until this kernel log buffer isnonempty, and then readsat mosti en bytesinto the buffer 
buf.lt returnsthenumber of bytes read. Bytesread from the log disappear from the log buffer; theinformation can only be 
read once Thisisthe function executed by the kernel when auser program reads/proc/kmsg. 

Thecall sysiog o.buf ,i en ) will read the last i en bytes from thelog buffer (nondestructively), but will not read morethan 
waswritten into the buffer si nce the last "clear ring buffer" command (which does not clear the buffer at ali). It returnsthe 
number of bytesread. 

Thecall sysiog (4,buf ,i en ) does precisely thesame, but also executes the "clear ring buffer" command. 
Thecall sysiog (5, d u mmy ,i dummy ) only executes the "clear ring buffer" command. 
THE LOG LEV EL 

The kernel routine printko will print a messageon the console only if it hasa loglevel lessthan thevalueof thevariable 
consoi e j ogi evei (initially default_console_loglevel (7), but set to 10 if the kernel command li ne contai ns the word debug, 
and to 15 in case of a kernel fault— the 10 and 15 are just silly, and are equi valent to 8). Thisvariableisset (to a valuein the 
rangel-8) by thecall sysiog (8, dummy ,vai ue ). Thecall sysiog (type, dummy ,i dummy ) with typeequal to 6 or 7, sets it to 1 
(kernel panicsonly) or 7 (ali except debugging messages), respectively. 

Everytext line in a messagehasitsown loglevel. This leve! ìsdefault_message_loglevel-i (6) unless the li ne starts with <d> 
whered is a digit in therangel-7, in which case the level isd. The conventi onal meaning of the loglevel isdefined in <imux/ 



kernel. h> asfollOWS: 










#def ine 


KERN 


EMERG 


"<0>" 


/* 


system is unusable 


* 


#def ine 


KERN 


ALERT 


"<1>" 


/* 


action must be taken immediately 


* 


#def ine 


KERN 


CRIT 


"<2>" 


/* 


criticai conditions 


* 


#def ine 


KERN_ 


ERR 


"<3>" 


/* 


error conditions 


* 


#def ine 


KERN 


WARNING 


"<4>" 


/* 


warning conditions 


* 


#def ine 


KERN^ 


NOTICE 


"<5>" 


/* 


normal but significant condition 


* 


#def ine 


KERN 


INFO 


"<6>" 


/* 


inf ormational 


* 


#def ine 


KERN 


DEBUG 


"<7>" 


/* 


debug -level messages 


* 



RETURN VALUE 

In case of error, -1 isreturned, and ermo is set. On success, fortype equal to 2, 3, or 4, sysiog o returnsthenumber of bytes 
read; otherwise, itreturnso. 

ERRORS 

eperm An atterri pt was madeto changeconsoie_iogievei or clear the kernel messagering buffer by a 

processwithout root permissions. 
einval Bad parameters. 

erestartsys System cali wasinterrupted by asignal— nothing was read. 
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CONFORMSTO 

Thissystem cali is Linux speci fic. 

SEEALSO 

syslog(3) 

Linux 1.2.9, 11 Junel995 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcf lush, 
tcf low, cf getospeed, cf getispeed, cf setispeed, cf setospeed, 
tcgetpgrp, tcsetpgrp 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, 

tcgetpgrp, tcsetpgrp— G et and set terminal attributes, do line control, get and set baud rate, get and set terminal foreground 
processgroup ID 

SYNOPSIS 

#include <termios.h> 
#include <unistd.h> 

int tcgetattr ( int f d , struct termios "termi osp ); 

int tcsetattr ( int f d , int o pt i ora I _ a c t i o ns , struct termios *t e r mi o s _ p ) ; 

int tcsendbreak ( int fd, int durati ori ); 

int tcdrain ( int f d ) ; 

int tcflush ( int fd, int queue_sel ector ); 

int tcflow ( int f d , int action ) ; 

speedjt cfgetospeed ( struct termios "termi os_p ); 

int cfsetospeed ( struct termios "termi osp, speedjt speed ); 

speedjt cfgetispeed ( struct termios "termi os p ); 

int cfsetispeed ( struct termios "termi osp, speed_t speed ); 

pid_t tcgetpgrp ( int f d ); 

int tcsetpgrp ( int fd, pid_t pgrpid ); 

DESCRIPTION 

Thetermiosfunctionsdescribeageneral terminal interface that isprovided to control asynchronous Communications ports. 

M any of thefunctionsdescribed herehaveater mi o s _ p argument that is a pointer to a termios structure. Thisstructure 
contai ns the following members: 

tcflag_t cjflag; /* input modes */ 

tcflag t c o f I a g ; /* output modes */ 

tcflag_t c c f I a g ; /* control modes */ 

tcflag_t cj f I ag ; /"locai modes*/ 
cct c_cc [NCCS] ; /* control chars */ 

Thefollowingarethecj f i a g flag constants 

ignbrk Ignore break condition on input. 

brkint If ignbrk isnot set, generate sigint on break condition; otherwise, read break ascharacter\0. 

ignpar Ignore framing errorsand parity errors. 

parmrk If ignpar isnot set, prefix a character with a parity errar or framing errar with \377 \0. If neither 

ignpar nor parmrk is set, read a character with a parity errar orframingerror as\0. 
inpck Enable input parity checking. 



termi os, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfseti speed, 

cfsetospeed, tcgetpgrp, tcsetpgrp 



istrip Strip off theeighth bit. 

inlcr Translate N L to CR on input. 

igncr Ignore carri age return on input. 

icrnl Translate carriage return to newlineon input (unless igncr is set). 

iuclc M ap uppercasecharactersto lowercaseon input. 

ixon EnableXON/XOFF flow control on output. 

ixany E nable any character to restart output. 

ixoff EnableXON/XOFF flow control on input imaxbel ring beli when input queueisfull. 
Thefollowing are the c_of lag fi ag con stants: 

opost Enableimplementation-defined output processing. 

olcuc M ap lowercasecharactersto uppercaseon output. 

onlcr M ap N L to C R-N L on output. 

ocrnl M ap C R to N L on output. 

onocr D on't output C R at column 0. 

onlret D on't output CR. 

ofill Sena fili charactersforadelay ratherthan useatimed delay. 

ofdel Fili character is ASC II DEL. If unset, fili character isASC 1 1 NUL. 

nldly N ewline delay mask. Values areica and nll 

crdly Carriage-return delay mask. ValuesarecRO, cri, cr2, and cr3. 

tabdly H orizontal-tab delay mask. ValuesareTABB, tabi, tab2, tab3, and xtabs. A valueof xtabs expands 

tabsto spaces(with tabstops every eight columns). 

bsdly Backspace delay mask. ValuesareBsa and bsl 

vtdly Vertical-tab delay mask. ValuesarevTo and vtl 

ffdly Form-feed delay mask. ValuesareFFa and ffl 

T h e f o 1 1 ovvi n g are the c_cf lag f I ag con stants: 

csize Character sizemask. Valuesarecss, cs6, cs7,and css. 

cstopb Set two stop bits rather than one 

cread Enablereceiver. 

parenb E nable parity generation on output and parity checkingfor input. 

parodd Parity for input and output isodd. 

hupcl Lower modem control li nes after last processcloses the device (hangsup). 

clocal Ignore modem control lines. 

cibaud Mask for input speeds(notused). 

crtscts Flow control. 

T h e f o 1 1 owi n g are the c_if lag f I ag con stants: 

isig When anyof thecharacters intr, quit, susp, orDsusp arereceived, generate the corresponding 

signal. 

icanon Enablescanonical mode. Thisallows the speci al characters eof, eol, eol2, erase, kill, reprint, 

status, and werase, and also buffersby lines. 
xcase If icanon isalso set, terminal isuppercaseonly. Input isconverted to lowercase, except for 

characters preceded by \. 0 n output, uppercase characters are preceded by \, and lowercase 

characters are converted to uppercase. 
echo Echo input characters. 
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echoe If icanon isalso set, the erase character erases the precedi ng input character, and werase erasesthe 

precedi ng word. 

echok If icanon isalso set, theKin character erases the cu rrent line 

echonl If icanon isalso set, echo theNL character even If echo isnot set. 

echoctl If echo isalso set, ASCII control signalsotherthan tab, nl, start, and stop areechoed asCtrl+X, 

whereX is the character with ASCII code 0x10 greaterthan thecontrol signal. Forexample, 
character 0x28 (BS) isechoed as C tri +H . 

echoprt If icanon and iecho arealso set, characters are pri nted asthey are bei ng erased. 

echoke If icanon isalso set, kill isechoed by erasing each character on the line, asspecified by echoe and 

echoprt. 

flusho Output isbeingflushed. Thisflag istoggled by typi ng the discard character. 

noflsh D isablesflushingof the input and output queueswhen generati ng the sigint and sigquit signals, 

and flushingof the input queuewhen generati ng thesiGsusp signal. 
tostop SendsthesiGTTou signal to the process group of a background processthat triesto writeto its 

controlli ng terminal. 

pendin Ali characters in the input queue are reprinted when the next character is read. (basti handles 

typeahead thisway.) 

iexten Enableimplementation-defined input processing. 

tcgetattro getstheparametersassociated with the object referred by f d and storesthem in thetermios structurereferenced 
byt ermi os p. Thisfunction may beinvoked from a background process; however, the terminal attributesmay besubse- 
quently changed by a foreground process. 

tcsetattro sets the parameters associated with the terminal (unlesssupport is required from theunderlying hardware that is 
not available) from thetermios structu re referred to by ter mi o s _ p . opt i onai _ a c t i ons specifieswhen thechangestakeeffect: 

tcsanow T he change occurs immediately. 

tcsadrain T he change occurs after ali output written to f d hasbeen transmitted. Thisfunction should beused 

when changing parameters that affect output. 
tcsaflush T he change occurs after ali output written to the object referred to by f d hasbeen transmitted, and 

ali input that hasbeen received but not read will bediscarded before the change ismade. 

tcsendbreako transmitsa continuous stream of zero-valued bits for a specific duration, if theterminal isusingasynchronous 
serial data transmission. If durati on is 0, ittransmits zero-valued bits for at least 0.25 seconds, and not morethan 0.5 
seconds. I f d u r a t i 0 n isnot e, it sends zero-valued bits for du rat on*N seconds, whereN isat least 0.25, and not more 
than 0.5. 

If theterminal is not usi ng asynchronous serial data transmission, tcsendbreako returns without taking any action, 
tcdraino waitsuntil ali output written to the object referred to by f d hasbeen transmitted. 

tcfiusho di scards data written to the object referred to by f d but not transmitted, or data received but not read, dependi ng 

on the vai ue ofqueue_sel ect or : 

tciflush Flushes data received but not read. 

tcoflush Flushes data written but not transmitted. 

tcioflush Flushes both data received but not read and data written but not transmitted. 

tcfiowo suspends transmission or reception of data on the object referred to byt d, dependi ng on thevalueof mi on: 

tcooff Suspends output. 

tcoon Restartssuspended output. 

tcioff Transmitsa stop character, which stops theterminal devi ce from transm i tti ng data to the system. 

tcion Transmitsa start character, which starts the terminal device transmitting datato the system. 



termi os, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfseti speed, 

cfsetospeed, tcgetpgrp, tcsetpgrp 



T he default on open of a terminal fileisthat neither its input nor its output issuspended. 

Thebaud rate functions are provi ded for getti ng and setti ng the valuesof the input and output baud ratesin thetermios 
structure. Thenew valuesdo not takeeffect until tcsetattr) > issuccessfully called. 

Setti ng the speed to bo instructs the modem to hang up. Theactual bit rate correspondingto B38400 may bealtered with 
setserial(8). 

Theinput and output baud ratesarestored in thetermios structure. 

cfgetospeed o returns the output baud ratestored in thetermios structure poi nted to by t e r mi o s _ p . 

cfsetospeed) ) setstheoutput baud ratestored in thetermios structure poi nted to by termi o s _ p to speed, which must beone 
of theseconstants: 

B0 

B50 

B75 

B110 

B134 

B150 

B200 

B300 

B600 

B1200 

B1800 

B2400 



B9600 

B19200 

B38400 

B57600 

B1 15200 

B230400 

Thezero baud rate, bo, isused to terminate the connection. If B0 isspecified, themodem control lineswill no longer be 
asserted. N ormally, thiswill disconnect the line cbaudex isa mask forthespeedsbeyond thosedefined in POSIX.l (57600 
and later). Thus, B57600 & cbaudex is nonzero. 

cfgetispeedi ) returns the input baud ratestored in thetermios structure. 

cfsetispeedo sets the input baud ratestored in thetermios structure to speed. If theinput baud rate is setto 0, it will be 
equal to the output baud rate 

tcgetpgrpo returns the process group ID of theforeground processi nggroup, or -1 on errar. 

tcsetpgrpo sets the process group ID to pgrpid. pgrpid must bethelD of a process group in thesamesession. 

RETURN VALUES 

cfgetispeedo returns theinput baud ratestored in thetermios structure. 
cfgetospeed!) returnstheoutput baud ratestored in the te rmios structure. 
tcgetpgrpo returnstheprocessgroup ID of foreground processi nggroup, or -1 on errar. 
Ali other functions return 
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a 0 n success. 

-1 on fai Iure (and set ermo to indicate theerror). 
SEEALSO 

setserial(8) 

Linux, 25 February 1995 

time 

time— G ets ti me i n seconds 
SYNOPSIS 

#include <time.h> 
time_t time(time_t *t ) ; 

D ESC RIPTIO N 

time return s the ti me si nce 00:00:00 GMT, January 1, 1970, measured in seconds. 
If t isnon nuli, the return valueisalso stored in thememory pointed to byt . 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

(Under BSD 4.3, thiscall is made obsolete by gettimeofday(2).) 

SEEALSO 

ctime(3), date(l), ftime(3), gettimeof day(2) 

Linux, 24 J uly 1993 

times 

times— G ets process ti mes 
SYNOPSIS 

#include <sys/times.h> 
clock_t times(struct tms *buf); 

DESCRIPTI0N 

times stores the current process times in b u f . 

struct tms isasdefined in /usr/include/sys/times.h: 

struct tms { 

time_t tms_utime; /* user time */ 

time_t tms_stime; /* system time */ 

time_t tms_cutime; /* user time of children */ 

time_t tms_cstime; /* system time of children */ 

}; 

times returnsthenumberof clock ticksthat haveelapsed si nce the system hasbeen up. 



truncate, ftruncate 




CONFORMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

time(l), getrusage(2), wait(2) 

Linux 0.99.11, 24 July 1993 

truncate, ftruncate 

truncate, ftruncate— T runcate a f i I e to a specified length 
SYNOPSIS 

#include <unistd.h> 

int truncate(const char *path, size_t length); 
int ftruncate(int f d , size_t I engt h ) ; 

D ESC RIPTIO N 

truncate causes the fi le named by patti or referenced by f d to be torneateci to at mosti engt h bytesin size. If thefile 
previ ously waslarger than thissize, the extra data islost. W ith ftruncate, the fi le must beopen forwriting. 

RETURN VALUE 

On success, e isreturned. On errar, -1 isreturned, and ermo isset appropriately. 

ERRORS 

T he errorsfor truncate are 



enotdir A componentof thepath prefixis nota directory. 

einval The pattinarne contains a character with the high-order bit set. 

enametoolong A component of a pathname exceeded 255 characters, or an entirepathnameexceeded 1,023 
characters. 

enoent T he named file doesnotexi st. 

eacces Search permission isdenied fora componentof thepath prefix. 

eacces T he named fi le is not writeable by the user. 

eloop Too many symbolic linkswereencountered in translati ng the pathname 

eisdir T he named fi le is a directory. 

erofs The named file resi deson a read-only filesystem. 

etxtbsy Thefile is a pure procedure (shared text) filethat is being executed. 

eio An I/O errar occurred updating the inode 

efault p a t h points outsidethe process's allocated address space. 

The errors for ftruncate are 

ebadf fd isnotavalid descriptor. 

einval f d references a socket, not a file. 

einval fd is not open forwriting. 



HI STORY 

Thesefunction callsappeared in BSD 4.2. 
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BUGS 

These calls should be general ized to allow rangesof bytes in afileto be di scardai 
SEEALSO 

open(2) 

BSD Man Page, 24 J uly 1993 

umask 

umask— Sets a fi le-creation mask 
SYNOPSIS 

«include <sys/stat.h> 
int umask(int mas k ) ; 

D ESC RIPTIO N 

umask SetS the umask tO mask & 0777. 

RETURN VALUE 

Thepreviousvalueof the mask isreturned. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

creat(2), open(2) 

L inux 24 J uly 93 

uname 

uname— Getsnameand information about thecurrent kernel 
SYNOPSIS 

«include <sys/utsname.h> 

int uname(struct utsname *buf); 

DESCRIPTION 

uname return S System information in buf . T he ut s na me StruCt isasdefined in /usr/include/sys/utsname.h: 

struct utsname { 

char sysname[65] ; 

char nodename[65] ; 

char release[65] ; 

char version[65] ; 

char machine[65] ; 

char domainname[65] ; 

}; 

RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 



afs_ syscal I r break, gtty, lock, mpx, prof, quotarti, stty, ustat 



ERRO RS 

efault buf isnotvalid. 

CONFO RMSTO 

SVID.AT&T, POSIX.X/OPEN 

SEEALSO 

uname(l), getdomainname(2), gethostname(2) 

Linux 0.99.11 24 July 93 

none 

none— U ndocumented system cai Is 

SYNOPSIS 

U ndocumented system calls. 

DESCRIPTION 

Asof Linux 1.3.88, therearel63 system calls listed in /usr/inciude/asm/unistd.n.Thisman page menti onsthose cai Isthat 
areimplemented in the kernel but not yet documented in man pages. Someof these calls do notyet haveprototypesin the 
libc include files. 

SO LICITANO N 

If you have informati on about these system calls, pleaselook in the kernel sourcecode, writea man page (using a stylesimilar 
to that of theother Linux section 2 man pages), and send itto aeb@cwi.ni for inclusion in thenext man page rei easefrom the 
Linux Documentation Project. 

STATUS 

U ndocumented are msync, readv, writev, getsid, f datasync, sysctl, sched_setparam, sched_getparam, sched_setscheduler, 
schedjjetscheduler, sched_yield, sched_get_priority_max, sched_get_priority_min, sched_rr_get_interval. 

SEEALSO 

obsolete(2), unimplemented(2) 

Linux 1.3.86 12 Aprii 1996 

af sjyscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat 

afs_syscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat— U ni mplemented System cai Is 

SYNOPSIS 

Unimplemented system calls. 

DESCRIPTION 

These system calls are not implemented in the Linux 1.2.4 kernel. 

RETURN VALUE 

These system calls always return -1 and set ermo to enosys. 



882 
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SEEALSO 

obsolete(2), undocumented(2) 

Linux 1.2.4, 15 Aprii 1995 

unlink 

uniink— D eletes a nameand possi bly the fi le it refersto 
SYNOPSIS 

#include <unistd.h> 

int unlink(const char "pattinarne); 

DESCRIPTION 

uniink deletes a name from thefilesystem. If that namewasthelast link to a file and no processeshavethefileopen, the fi le 
is deleted, and the space it wasusing is made availablefor reuse. 

If the namewasthelast link to a file but any processes stili havethefileopen, the fi le wi II remain in existenceuntil thelast 
fi le descriptor referringto it isclosed. 

If the name referred to asymbolic link, the link isremoved. 

If the name referred to asocket, fifo, or device, the name for it isremoved but processes that have the object open can 
conti nueto useit. 

RETURN VALUE 

On success, e isreturned. 0 n errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

efault p a t h n a me poi nts outside your accessi ble address space. 

eacces Write access to the directory contai ni ng pat n nane isnot allowed for the process'seffecti vel) ID, or 

oneof thedirectoriesin pat hname did not allow search (execute) permission. 

eperm Thedirectory containingpathname hasthesticky bit (s_isvtx) set, and the process'seffecti ve UID is 

neither theLI ID of the file to be deleted northat of thedirectory contai ni ng it, or pat hname isa 
directory. 

ENAMETOOLONG p a t h n a me waS tOO long. 

enoent A directory component in pattinarne doesnot exist or isa dangling symbolic link. 

enotdir A component used as a directory in pat hname isnot, in fact, a directory. 

eisdir pat hname refersto a directory. 

enomem I nsuffi ci ent kernel memory wasavailable. 

erofs pat hname refers to a fi le on a read-only filesystem. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

BUGS 

I nfel i citi es in the protocol underlying N FS can cause the unexpected disappearanceof fi les that are stili bei ng used. 
SEEALSO 

link(2), rename(2), open(2), rnidir(2), mknod(2), mkfifo(3), remove(3), rm(l), unlink(8). 

Linux, 24 J uly 1993 



ustat 




uselib 

useiib— Selectsshared library 
SYNOPSIS 

#include <unistd.h> 

int uselib(const char 'library); 

DESCRIVO N 

useiib selects the shared library binarythatwi II beused by this process. 
RETURN VALUE 

On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

In additi on to ali the errar codes returned by open(2) and mmap(2), thefollowing may also bereturned: 

enoexec T he file specified by i i b r a r y isnotexecutable, ordoesnothavethecorrect magic numbers. 

eacces Thelibraryspecified by i i brary isnot readable. 

C0NF0RMST0 

useiibo is Linux specific. 

SEE ALSO 

open(2), mmap(2), ldd(l), gcc(l), ar(l), ld(l) 

Linux 0.99.11, 24 July 1993 

ustat 

ustat— Gets fi lesystem statisti cs 
SYNOPSIS 

#include <sys/types.h> 

int ustat(dev_t d e v , struct ustat * ubuf); 

DESCRIPTION 

ustat returnsinformation about a mounted fi lesystem. dev is a device number identifying adevice containing a mounted 
fi lesystem. ubuf isa pointer to a ustat structurethat containsthefollowing members: 

daddr_t f_tfree; /* Total free blocks */ 
ino_t f_tinode; /* Number of free inodes */ 
char f_fname[6]; /* Filsys name */ 
char f_fpack[6]; /* Filsys pack name */ 

Thelasttwo fields, f_fname and f_fpack, arenot implemented and will always befilled with nuli characters. 
RETURN VALUE 

On success, 0 isreturned, and the ustat structurepointed to by ubuf will befilled in. On errar, -1 isreturned, and ermo is 
set appropriately. 
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ERRO RS 

einval dev does not refer to a devi ce contai ni ng a mounted filesystem. 

efault j b jf pointsoutsideof your accessibleaddress space. 

enosys The mounted filesystem referenced by dev doesnotsupport this operation, or any versi on of Linux 

before 1.3.16. 

NOTES 

ustat hasbeen provided forcompatibility only. Ali new programsshould usestatfs(2) instead. 
HISTORY 

ustat was first implemented in Linux 1.3.16. Ali versionsof Linux before 1.3.16 will return enosys. 

C0NF0RMST0 

System V 

SEEALSO 

statfs(2), stat(2) 

Linux 1.3.16, 9 August 1995 

utime, utimes 

utime, utimes— Change access and/or modificati on timesof an inode 
SYNOPSIS 

#include <sys/types.h> 
#include <utime.h> 

int utime(const char *f i I e n a me , struct utimbuf *buf); 
#include <sys/time.h> 

int utimes(char *f i I e n a me , struct timeval *tvp); 

DESCRIPTION 

utime changes the access and modification timesof the inode specifi ed by f i i ename to the a c t i me and modt i me fieldsof buf , 
respectively. If buf isN U LL, the access and modification timesof the fi le are set to thecurrent ti me The utimbuf structureis 

struct utimbuf { 

time_t actime; /* access time */ 
time_t modtime; /* modificaticn time */ 

>; 

In the Linux D LL 4.4.1 libraries, utimes is just a wrapper for utime, t vp [0] .t v_sec isact i me, and tvp m .tv_sec ismodti me. 
Thetimevai structureis 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 

>; 



RETURN VALUE 

On success, e isreturned. On errar, -1 isreturned, and ermo isset appropriately. 



vm86 




ERRO RS 

Othererrorsmayoccur. 

eaccess Permission to writethefile isdenied. 

ENOENT filename doesnOtexiSt. 

C0NF0RMST0 

utime: 5VID, POSIX 
utimes:BSD 4.3 

SEEALSO 

stat(2) 

Linux, 10 Junel995 

vhangup 

vhangup— Virtual ly hangsup thecurrent tty 
SYNOPSIS 

#include <unistd.h> 
int vhangup(void) ; 

D ESC RIPTIO N 

vhangup simulates a hangup on thecurrent terminal. This cali arrangesfor other usersto haveaclean tty at login ti me 
RETURN VALUE 

On success, 0 isreturned. 0 n errar, -1 isreturned, and ermo isset appropriately. 
ERRORS 

eperm The user isnotthesuperuser. 

SEEALSO 

init(8) 

Linux 0.99.11, 24 July 1993 

vm86 

vm86— E nters vi rtual 8086 mode 
SYNOPSIS 

#include <sys/vm86.h> 

int vm86(struct vm86_struct * info); 

DESCRIPTION 

EnterVM 86 modewith information asspecified in i n f 0 : 

struct vm86_struct { 

struct vm86_regs regs; 
unsigned long flags; 
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unsigned long screen_bitmap; 



}; 



struct vm86_regs { 
/* 

* normal regs, with special meaning for the segment descrìptors. . 

*/ 

long ebx; 

long ecx; 

long edx; 

long esi; 

long edi; 

long ebp; 

long eax; 

long null_ds; 

long null_es; 

long null_fs; 

long null_gs; 

long orig_eax; 

long eip; 

long cs; 

long eflags; 

long esp; 

long ss; 

/* 

* these are specific to v86 mode: 
*/ 



these are specific to v86 mode: 

/ 

long es; 
long ds; 
long fs; 
long gs; 

}; 



On success, 0 isreturned. On errar, -1 isreturned, and ermo isset appropriately. 



long 
long 
long 
long 



es; 
ds; 
fs; 

gs; 



}; 



RETURN VALUE 



ERRORS 



EPERM 



Saved kernel stack exists. 



Linux 0.99.11, 24 July 1993 




watt, waitpid— Waitfor process termination 



SYNOPSIS 



#include <sys/types.h> 
#include <sys/wait.h> 



wait, waitpid 



pid_t wait(int *s t a t u s ) 

pid_t waitpid (pid_t pi d , int*s t a t us ,int opti o n s ) ; 

D ESC RIPTIO N 

Thewait function suspendsexecution of the current process unti I achild hasexited, oruntil asignal isdelivered whose 
action isto termi nate the current processor to cali a signal-handling function. If achild has al ready exited Py the ti me of the 
cali (aso-called zombie process), the function returns immediately. Any system resourcesused Py the chi Id arefreed. 

The waitpid function suspendsexecution of the current process unti I achild asspecified by the p i d argument hasexited, or 
until a signal isdelivered whose action isto termi nate the current processor to cali a signal-handling function. Just aswith 
wait, if achild requested by p i d has al ready exited by the time of the cali, thefunction returns immediately. Any system 
resources used Py the chi Id are f reed. 

Thevalueof pi d can Peone of thefollowing: 

< -1 W ait for any child process whose process group ID isequal to theaPsolute valueof pi d. 

-1 Wait for any child process; thisisthesamePehaviorthatwait exhiPits. 

0 Wait for any child process whose process group ID isequal to that of the calli ng process. 

> 0 Wait for the child whose process ID isequal to thevalueof pi d. 

Thevalueof opt ons isan OR of zero or more of thefollowing constants: 
wnohang Return immediately if no child hasexited. 

wuntraced Also return for children that arestopped and whose status has not Peen reported. 

If status isnot null, wait or waitpid stores status informati on in the location pointed to Py st ati oc. 

This status can Peevaluated with thefollowing macros(thesemacrostakethestat Puffer asan argument— not a pointer to 
the buffer!): 

wiFExiTED(status ) Isnonzero if thechild exited normally. 

wExiTSTATus(status ) Evaluatesto theleast significai eight bitsof the return code of thechild that termi nated, which 

may havebeen set as the argument to a cali to exito or as the argument for a return statement 
in the mai n program. This macro can only Peevaluated if wifexited returned nonzero. 

wifsignaled(s t at us ) Returns true if the child process exited Pecauseof asignal that was not caught. 

wTERMsiG(st at us ) Returns the numPer of the signal thatcaused thechild process to terminate. This macro can 

only Peevaluated if wifsignaled returned nonzero. 

wiFSTOPPED(status ) Returnstrue if thechild process that caused the return iscurrently stopped; this is only possi Pie 

if the cali was done usi ng wuntraced. 

wsTOPsiG(status ) Returns the numPer of the signal thatcaused thechild to stop. This macro can only Pe 

evaluated if wifstopped returned nonzero. 

RETURN VALUE 

The process ID of thechild that exited returns -1 on errar or 0 if wnohang was used and no child was available (in which case 
errno issetto an appropriate value). 

ERRORS 

echild If thechild process speci fi ed in pi d doesnotexist. 

eperm If the effective user I D of the calli ng process does not match that of the process Peingwaited 

for, and the effective user ID of the cali i ng process isnot that of the superuser. 

erestartsys If wnohang was notset and an unPIocked signal or a sigchld was caught; this isan extension to 

thePOSIX.l standard. 
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CONFORMSTO 

POSIX.l 

SEEALSO 

signal(2), wait4(2), signal(7) 

Linux, 24 J uly 1993 



wait3,wait4 

wait3, waìt4— Waitfor processtermination, BSD style 
SYNOPSIS 

#define _USE_BSD 

#include <sys/types.h> 

#include <sys/resource.h> 

#include <sys/wait.h> 

pid_t wait3 ( int *s t a t u s , int opti o n s , 

struct rusage *r usage ) ; 

pid_t wait4(pid_t pi d ,int*st at us ,int opti o n s , 
struct rusage *r usage ) ; 



DESCRIPTION 

Thewait3 function suspendsexecution ofthecurrent process until achild hasexited, oruntil asignal isdelivered whose 
action isto termi nate the current processor to cali a signal-handling function. If achild has al ready exited by the ti me of the 
cali (a zombie process), the function returnsimmediately. A ny system resourcesused by the chi Id arefreed. 

Thewait4 function suspendsexecution ofthecurrent process until a child asspecified by the pi d argument hasexited, or 
until asignal isdelivered whose action isto termi nate the current processor to cali a signal-handling function. If achild as 
requested by pi d has al ready exited by the ti me of the cali (a zombie process), the function returnsimmediately. A ny system 
resources used by the chi Id are f reed. 

Thevalueof pi d can beoneof the following: 

< -1 Waitforany child process whose process group ID isequal to theabsolute valueof pi d. 

-1 Waitforany child process; thisisequivalentto calli ng wait3. 

a Waitfor any child process whose process group ID isequal to that of the calli ng process. 

> 0 W aitfor the child whose process ID isequal to thevalueof pi d. 

Thevalueof opt ons isan exclusiveOR of zero or more of the following constante 

wnohang Return immediately if no child isthereto bewaited for. 

wuntraced Also return for children that arestopped and whose status has not been reported. 

If status isnot null, wait3 and wait4 store status information in the location pointed to by stati oc. 
Thisstatuscan beevaluated with thefollowing macros: 
wiFExiTED(*status ) Isnonzero if thechild exited normally. 

wExiTSTATusrstatus ) Evaluatesto theleast significai eight bitsof the return code of thechild that termi nated, which 
may nave been set as the argument to a cali to exit or as the argument for aret urn statement in 
themain program. Thismacro can only beevaluated if wifexited returned nonzero. 

wiFsiGNALED(*st at us ) Returnstrue if the child process exited becauseof asignal that was not caught. 

wTERMsiG(*status ) Returns the number of the signal thatcaused thechild process to terminate. Thismacro can 

only beevaluated if wifsignaled returned nonzero. 



Write 

wiFSTOPPED(*status ) Returnstrue if the chi Id processthat caused the return iscurrently stopped; thisisonly possi ble 

if the cali was done usi ng wuntraced. 
wsTOPSiG(*status ) Returns the number of the signal that caused the chi Id to stop. Thism acro can only be 

evaluated if wifstopped returned nonzero. If rusage is not null, thestruct rusage asdefined in 

<sys/resource.h> it pointsto will be fi lied with accounting information. Seegetrusage(2) for 

details. 

RETURN VALUE 

These cai Is return theprocessID of the chi Id that exited, -1 on errar, ora if wnohang wasused and no child wasavailable(in 
which case ermo will besetappropriately). 

ERRORS 

echild If thechild processspecified in pi d does not exist. 

eperm If theeffectiveuser ID of the calli ng process does not match that of the process bei ngwaited 

for, and theeffectiveuser ID of the cali i ng process is not that of the superuser. 

erestartsys If wnohang was notset and an unblocked signal or a sigchld wascaught; thisisan extension to 

the PO SIX.l standard. 

CONFO RMSTO 

POSIX.l 

SEEALSO 

signal(2), getrusage(2), wait(2), signal(7) 

Linux, 24 J uly 1993 



write 

write— W ri testo afiledescriptor 
SYNOPSIS 

#include <unistd.h> 

ssize_t write (int fd, const void *buf , size_t count); 

DESCRIPTION 

write writesup to count bytes to the file referenced by the file descri ptor f d from the buffer starting atbuf . PO SIX requires 
thatareado that can beprovedto occur after a write o returned returns the new data. Notethatnotall filesystemsare 
PO SIX conformi ng. 

RETURN VALUE 

On success, the number of bytes written is returned (0 indicates nothing waswritten). On errar, -1 is returned, and ermo is 
set appropriately. If count ise and the fi le descri ptor refersto a regular file, 0 will be returned without causi ngany other 
effect. For a special file, theresultsarenot portable. 

ERRORS 

ebadf fd isnotavalidfiledescriptororisnotopen forwriting. 

einval fd isattached to an object that is unsuitable for writing. 

efault buf isoutside your accessible address space. 
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epipe f d isconnected to a pipe or socketwhosereading end isclosed. W hen thishappens, thewriting 

process will receiveasiGPiPE signal; if it catches, blocks, or ignoresthis, the errar epipe is 
returned. 

eagain Non-blocking I/O hasbeen selected usingo_NONBi_ocK, and therewasno room in the pipe or 

socketconnectedtofdtowritethedataimmedi atei y . 
eintr The cali was interra pted by a signal beforeany datawaswritten. 

enospc Thedevicecontainingthefilereferred to by f d hasno room forthedata. 

Other errorsmay occur, depending on the object connected to f d . 
CONFO RMSTO 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

SEEALSO 

open(2), read(2), fcntl(2), close(2), lseek(2), select(2), ioctl(2), fsync(2), fwrite(3) 

Linux, 13 J anuary 1996 



Partili: 



Library Fu nctions 




Part III: Library Functions 



Intro 

D ESC RIFTIO N 

This chapter descri bes ali the library functions, excluding the library functions described in Part 2, which i m pi ement system 
cai Is. The vari ousfunction groups are i dentified by aletter that isappended to the chapter number: 



(3C) T hese functions— the functions from Chapter 2 and from Chapter 3S— arecontained in the C standard 

library libc, which will beused by cc(l) by default. 
(3S) T hese functions are partsof the stdio(3S) library. They arecontained in the standard C library iit>c. 

(3M ) Thesefunctionsarecontained in the arithmetic library ìibm. They are used bythet77(l) FORTRAN 

compiler by default, but not by thecc(l) C compiler, which needs the option - m. 
(3F) T hese functions are part of the FORTRAN library iibF77. There are no special compiler flagsneeded to 

use these functions. 

(3X) V ari ous special libraries. Themanual pages documenting thér functions specify the library names. 



AUTHORS 

Look at theheader of themanual page for the author(s) and copyright conditions. N ote that these can bedifferent from page 
to page! 

Linux, 13 December 1995 

abort 

abort— Causesabnormal program terminati on 
SYNOPSIS 

«include <stdlib.h> 
void abort(void) ; 

D ESC RIFTIO N 

The aborto function causesabnormal program termi nati on unlessthesignal sigabort iscaught and thesignal handler does 
not return. If the aborto function causes program termination, ali open streamsareclosed and flushed. 

If the sigabort function isblocked or ignored, the aborto function will stili overrideit. 

RETURN VALUE 

The aborto function never return s. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

sigaction(2), exit(3) 

GNU, 12 Aprii 1993 



abs 

abs— Computestheabsolutevalueof an integer 



SYNOPSIS 

#include <stdlib.h> 
int abs(int j ) ; 

DESCRIPTION 

Theabso function computestheabsolutevalueoftheintegerargumentj . 

RETURN VALUE 

Retums the absolute value of the integer argument. 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

NOTES 

T rying to take the absolute value of the most negative i nteger is not defi ned. 
SEEALSO 

ceil(3), f loor(3), f abs(3), labs(3), rint(3) 

GNU,6Junel993 

acos 

acos— Are cosi ne function 
SYNOPSIS 

#include <math.h> 
doublé acosfdouble x ) ; 

DESCRIPTION 

The acoso function calculates the are cosi ne of x; that is the value whose cosi ne isx. I f x falls outsidethe range-1 to 1, 
acoso failsand ermo isset. 

RETURN VALUE 

Theacoso function retums the are cosi ne in radians; the valueis mathematically defi ned to bebetween 0 and pi (inclusive). 

ERRORS 

edom x isoutof range. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

asin(3), atan(3), atan2(3), cos(3), sin(3), tan(3) 

8 Junel993 



acosh 

acosh— Inverse hyperbolic cosinefunction 
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SYNOPSIS 

#include <math.h> 
doublé acosh (doublé x ) ; 

DESCRIPTION 

The acosh o function calculates the inverse hyperbolic cosine of x ; that isthevaluewhosehyperbolic cosi ne isx . If % isless 
than 1.0, acosh o returnsnot-a-number (N aN ), and ermo is set. 

ERRO RS 

edom x isoutof range. 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

asinh(3), atanh(3), cosh(3), sinh(3), tanh(3) 

13 Junel993 

alloca 

alloca— M emory allocator 
SYNOPSIS 

#include <stdlib.h> 

void *alloca( size_t si z e ) ; 

DESCRIPTION 

The alloca function allocatessi ze bytesof space in thestackframeof the Caller. Thistemporary space isautomatically freed 
on return. 

RETURN VALUES 

The alloca function returns a pointer to thebeginning of the allocateci space. If the al location fails, aNULL pointer is 
returned. 

CONFO RMSTO 

Thereisevidence that the alloca function appeared in 32v, pwb, pwb.2, 3bsd, and4bsd.Thereisaman pageforitin BSD 
4.3. Linux usestheGN U version. 

BUGS 

The alloca function is machine dependent. 
SEEALSO 

brk(2), pagesize(2), calloc(3), malloc(3), realloc(3) 

GNU, 29 Novemberl993 

asin 

asin— Are sinefunction 



SYNOPSIS 

#include <math.h> 
doublé asin(double x ) ; 

DESCRIPTION 

The asino function calculates the are sineof x, which isthevaluewhosesineisx. I f x falls outside the range -1 to 1, asino 
fai Is and ermo is set. 

RETURN VALUE 

The asino function returns the are sine in radians, and thevalue is mathematically defined to bebetween -pi/2 and pi/2 
(inclusive). 

ERRORS 

edom x isoutof range. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acos(3), atan(3), atan2(3), cos(3), sin(3), tan(3) 

8Junel993 

asinh 

asinh— Inverse hyperbolic sinefunction 
SYNOPSIS 

#include <math.h> 
doublé asinh (doublé x ) ; 

DESCRIPTION 

The asinh o function calculates the inverse hyperbolic sine ofx—thatis, the valuewhose hyperbolic si ne isx. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acosh(3), atanh(3), cosh(3), sinh(3), tanh(3) 

13 Junel993 

assert 

assert—Abort the program if assertion isfalse 
SYNOPSIS 

#include <assert.h> 

void assert (int expressi or ); 
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DESCRIPTION 

asserto printsan errar messageto standard output and terminate the program by calli ng aborto if ex press i on is false (that 
is, evaluatesto 0). Thisonly happenswhen themacro ndebug isundefined. 

RETURN VALUE 

No valueisreturned. 

C0NF0RMST0 

ISO 9899 (ANSI C) 

BUGS 

asserto is implemented asa macro; if theexpression tested has side effects, program behavior wi II bedifferent dependingon 
whether ndebug is defi ned. T hi smay create H eisenbugs, which go away when debugging isturned on. 

SEEALSO 

exit(3), abort(3) 

G N U , 4 Aprii 1993 

atan 

atan— Are tangent function 
SYNOPSIS 

#include <math.h> 
doublé atan(double x ) ; 

DESCRIPTION 

Theatano function calculates the are tangent of x — that is, the valuewhose tangent isx. 
RETURN VALUE 

Theatano function returns the are tangent in radians, and the value is mathematically defined to bebetween -pi/2 andpi/2 
(inclusive). 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acos(3), asin(3), atan2(3), cos(3), sin(3), tan(3) 

8 Junel993 

atan2 

atan2— Are tangent function of two variables 
SYNOPSIS 

#include <math.h> 

doublé atan2 (doublé y, doublé x); 



atexit 




DESCRIPTION 

Theatan2(> function calculates the are tangent of thetwo variables, x andy. Itissimilarto calculati ng the are tangent of y/x, 
except that the sines of both argumentsareused to determi ne the quadrant of the result. 

RETURN VALUE 

Theatan2() function returnsthe result in radians, which isbetween -pi and pi (inclusive). 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acos(3), asin(3), atan(3), cos(3), sin(3), tan(3) 

8 Junel993 

atanh 

atanh— I nverse hyperbolic tangent function 
SYNOPSIS 

#include <math.h> 
doublé atanh (doublé x ) ; 

DESCRIPTION 

The atanh o function calculates the inverse hyperbolic tangent of x; that is the valuewhose hyperbolic tangent isx. If the 
abso Iute vai ueof x isgreater than 1.0, acosho returnsnot-a-number (N aN ), and ermo isset. 

ERRORS 

edom x isoutof range. 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

asinh(3), acosh(3), cosh(3), sinh(3), tanh(3) 

13 Junel993 

atexit 

atexit— Register a function to becalled at normal program termination 
SYNOPSIS 

#include <stdlib.h> 

int atexit(void *f unct i on ) (void) ) ; 

DESCRIPTION 

The atexit o function registersthe given function to becalled at normal program termination, whether viaexit(2) or via 
return from the program 'smain. Functionsso registered arecalled in the reverse orderof their registrati on; no argumentsare 
passed. 
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RETURN VALUE 

Theatexitofunction returnsthevaluea if successful; otherwise, thevalue-1 isreturned, and theglobal variableerrno isset 
to indicate the errar. 

ERRORS 

enomem Insufficient memory availableto add thefunction. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

exit(3), on exit(3) 

GNU, 29 March 1993 

atof 

atof— Converta stri ngto a doublé 
SYNOPSIS 

#include <stdlib.h> 

doublé atof(const char *nptr); 

DESCRIPTION 

T he atof o function convertsthe initial portion of the stri ng pointed to by npt r to doublé. The behavior isthesameas 

strtod(nptr, (char **)NULL); 

except that atof o does not detect errors. 

RETURN VALUE 

Theconverted value. 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

atoì(3), atol(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 March 1993 

atoi 

atoi— C onvert a stri ng to an integer 
SYNOPSIS 

#include <stdlib.h> 

int atoi(const char *nptr); 



bcmp 



DESCRIPTION 

Theatoio function convertsthe initial portion of the stri ng poi nted to by npt r to int. Thebehavior isthesameas 

strtol(nptr, (char **)NULL, 10); 

except that atoi( ) does not detect errors. 

RETURN VALUE 

Theconverted value 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

atof(3), atol(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 M arch 1993 



atol 

atoi— Converta stri ngto alonginteger 
SYNOPSIS 

#include <stdlib.h> 

long atol(const char *nptr); 

DESCRIPTION 

Theatoio function convertsthe initial portion of the stri ng poi nted to by npt r to long. Thebehavior isthesameas 

strtolfnptr, (char **)NULL, 10); 

except that atoi( > does not detect errors. 

RETURN VALUE 

Theconverted value 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

atof(3), atoi(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 March 1993 



bcmp 

bcmp— C ompare byte stri ngs 
SYNOPSIS 



#include <string.h> 

int bcmp(const void *sl, const void *s2, int n ) ; 
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DESCRIVO N 

Thebcmpo function compares the first n bytesof the strings s 1 and s2. Ifthetwo strings are equal, bcmpo returnse; 
otherwise, it returns a nonzero result. If n isa, thetwo strings are assumed to be equal. 

RETURN VALUE 

Thebcmpo function returnso if the strings are equal; otherwise, a nonzero result isreturned. 
C0NF0RMST0 

4.3BSD . T his function is deprecateci— use memcmp i n new programs. 
SEEALSO 

memcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncmp(3), strncasecmp(3) 

GN U, 9 Aprii 1993 

bcopy 

bcopy— Copy byte strings 
SYNOPSIS 

#include <string.h> 

void bcopy (const void *src, void*d est, int n); 

DESCRIVO N 

The bcopy o function copies the first n bytesof the source stri ng s r c to the desti nati on stri ng d e s t . If n isO, no bytesare 
copied. 

RETURN VALUE 

The bcopy o function returns no value. 

CONFO RMSTO 

4.3BSD . T his function is deprecateci— use memcpy i n new programs. 
SEEALSO 

memccpy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3) 

GN U, 9 Aprii 1993 

bsearch 

bsearch— Binary search of a sorted array. 
SYNOPSIS 

#include <stdlib.h> 

void *bsearch(const void *key, const void "base, size_t nmemb, 
size_t s i z e , int(*c o mpa r ) (const void *, const void *)); 

DESCRIPTION 

The bsearch o function searchesan array of nmemb objects, theinitial member of which ispointed to by base, fora member 
that matchestheobject pointed to by key. Thesizeof each member of the array isspecified by si ze. 

The contentsof the array should bein ascendi ng sorted order accordi ng to the compari son function referenced by c o mpa r . 



htonl, htons, ntohl , ntohs 




Thecompar routine is expected to havetwo argumentsthat point to thekey object and to an array member, in that order, and 
should return an integer lessthan, equal to, or greater than 0, respecti vely, if thekey object isfound to belessthan, match, or 
be greater than the array member. 

RETURN VALUE 

Thebsearcho function returns a pointer to a matching member of the array, orNun if no match isfound. If thereare 
multiple elementsthat match thekey, theelement returned is unspecified. 

CONFO RMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

qsort(3) 

GNU, 29 March 1993 

bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memf rob, 
memmem, memmove,memset 

bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memf rob, memmem, memmove, memset — Byte Stri n g Operations 

SYNOPSIS 

#include <string.h> 

int bcmp(const void *sl, const void *s2, int n ) ; 
void bcopy(const void *src, void *d e s t , int n); 
void bzero(void *s , int n); 

void *memccpy (void *d est , const void *src, int c, size_t n); 

void *memchr(const void *s , int c, size_t n); 

int memcmp(const void *sl, const void *s2, size_t n); 

void *memcpy(void *d e s t , const void *src, size t n); 

void *memf rob (void *s , size_t n); 

void *memmem( const void *n e e d ! e , size_t needlelen, 

const void *haystack, size_t hayst ackl en ) ; 

void "memmove (void *d est , const void *src, size_t n); 

void *memset(void *s , int c, size_t n); 

DESCRIPTION 

The byte stri ngfunctionsperform operations on stri ngs that arenot N U LL termi nated. See the individuai man pagesfor 
descriptionsof each function. 

SEEALSO 

bcmp(3), bcopy(3), bzero(3), memccpy(3), memchr(3), memcmp(3), memcpy(3), memf rob(3), memmem(3), memmove(3), memset(3) 

GNU, 12 Aprii 1993 

htonl, htons, ntohl, ntohs 

htoni, htons, ntohi, ntohs— C onvert values between host and network byte order 
SYNOPSIS 



#include <netinet/in . h> 

unsigned long int htonl(unsigned long int hostl ong); 
unsigned short int htons(unsigned short int hostshort); 
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unsigned long int ntohl(unsigned long int netlong); 
unsigned short int ntohs(unsigned short int netshort); 

DESCRIVO N 

Thehtonio function converts the long integer host ! ong from host byteorderto network byteorder. 

Thehtonso function converts the short integer host short from host byteorderto network byteorder. 

Thentonio function converts the long integer net i ong from network byteorderto host byteorder. 

Thentonso function converts the short i nteger netshort from network byteorderto host byteorder. 

On the i 80x86, the host byteorder isleast significant byte first, whereas the network byteorder, asused on the Internet, is 
mostsignificant byte first. 

C0NF0RMST0 

BSD 4.3 

SEEALSO 

gethostbyname(3), getservent(3) 

BSD, 15 Aprii 1993 

bzero 

bze ro— W ri tes os to a byte stri ng 
SYNOPSIS 

#include <string.h> 

void bzero(void *s , int n); 

D ESC RIPTIO N 

Thebzeroo function setsthefirst n bytes of the byte stri ng s toO. 

RETURN VALUE 

Thebzeroo function returnsno value. 

C0NF0RMST0 

4. 3BSD .This function isdeprecated— usememset in new programs. 
SEEALSO 

memset(3), swab(3) 

GNU, 9 Apri 1 1993 

catgets 

catgets— Gets messagefrom a messagecatalog 
SYNOPSIS 

#include <features.h> 
#include <nl_types.h> 

char *catgets(nl_catd catalog, int set_number, int 
messagenumber, char *message); 



catopen, catcl ose 



DESCRIVO N 

catgets() reads the messagemessage_number, in set set_number, from the message catalog i dentifi ed by catal og. {catal og isa 

catalog descriptor returned from an earlier cali to catopen(3).) Thefourth argument message pointsto a default message 
stri ng that wi 1 1 be returned by catgetso if the identified message catalog is not currently open or isdamaged. The message 
text i scontai ned in an internai buffer area and should becopied by the application if it isto besaved or modified. The return 
stri ng isalwaysterminated with a nuli byte. 

RETURN VALUES 

On success, catgetso return s a pointer to an internai buffer area containingthenull-terminated message stri ng. catgetso 
returns a pointer to message if itfails because the message catalog speci fi ed by catalog isnot currently open. Otherwise, 
catgetso return s a pointer to an empty stri ng if the message catalog isavailablebut doesnot contain thespecified message. 

NOTES 

Thesefunctionsareonly availablein iibc.so.4.4.4c and above. 
SEEALSO 

catopen(3), setlocale(3) 

29 N ovember 1993 

catopen, catclose 

catopen, catclose— 0 pen/close a message catalog 
SYNOPSIS 

#include <features.h> 

#include <nl_types.h> 

ni catd catopen(char *name, int flag); 

void catclose(nl_catd catalog); 

DESCRIPTION 

catopeno opens a message catalog and returns a catalog descriptor. na me specifies the nameof the message catalog to be 
opened. I f n a me specifies an absolute path (that is, containsa /), name specifies a pathnamefor the message catalog. Otherwise, 
the environment vari able nlspath isused, with name substituted for %n (seeiocaie(5)). If nlspath doesnot exist in the 
environment, or if a message catalog cannot beopened in any of the pathsspecified by nlspath, thefollowing pathsare 
searched in order: 

/etc/locale/LCJIESSAGES 

/usr/lib/locale/LC_MESSAGES 

/usr/lib/locale/name/LC_MESSAGES 

In ali cases, lc_messages stands for the current setti ngof the lcjessages category of locai e from a previ ous cali to 
setiocaieo and defaultsto theC" locale. In the last search path, name refersto the catalog name. 

T he f i ag argument to catopen isused to indicate the typeof loadingdesired. Thisshould beeithericLoadByset or MCLoadAii. 
Theformer valueindicatesthat onlytherequired set from the catalog isloaded into memory when needed, whereasthelatter 
causestheinitial cali to catopeno to load the enti re catalog into memory. 

catcìoseo closesthemessagecatalog identified by catal og. It invalidatesany subsequent referencesto the message catalog 
defined by catal og. 

RETURN VALUES 

catopeno returns a message catalog descriptor of typem_catd on success. 0 n fai Iure it returns -1. 
catcìoseo returnso on success, or -1 on failure. 



Part III: Library Functions 



NOTES 

T hese functions are only available in libc.so.4.4.4c and above. In the case of Linux, the catalog descri ptor m_catd isactually 
an area of memory assigned by mmapo and not a file descri ptor, thus allowing catalogsto beshared. 

SEEALSO 

catgets(3), setlocale(3) 

30 N ovember 1993 

ceil 

ceii— Smallest integrai valuenot lessthan x 
SYNOPSIS 

#include <math.h> 
doublé ceil (doublé x ) ; 

D ESC RIPTIO N 

Theceiio function roundsupx to thenearest integer, returni ngthat valueas a doublé. 
CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

abs(3), fabs(3), f loor(3), labs(3), rint(3) 

6 Junel993 

clientlib 

ciientiib— N NTP clientlib part of InterN etN ews library 
SYNOPSIS 

extern FILE *ser_rd_fp; 

extern FILE *ser_wr_fp; 

extern char ser_line[]; 

char * getserverbyf ile(f i I e ) ; 

char *file; int server_init(host ) ; 

char *host; 

int handle_server_response (r es po ns e , host); 
int reponse; 
char *host ; 

void put_server(t ext ) ; 
char *t ext ; 

int get_server(buf f , buffsize); 

char *buf f ; 

int buffsize; 

void close_server() ; 

DESCRIPTION 



The routines descri bed in thismanual page are part of the InterN etN ews library, iibinn(3).Theyarereplacementsforthe 
clientlib part of theN NTP distri bution, and areintended to beused in building programssuch asrrn. 



closedir 




getserverbyfiie calls Getconf igvaiue to get the name of the locai N NTP server. It returns a pointer to stati c space. The f i e 
parameterisignored. 

serverinit opens a connect to the N NTP server at thespecified h o s t . It returns the server's response code or -1 on error. If 
a connection was made, ser_rd_f p and ser_wr_t p can be used to read from and write to the server, respectively, and ser_iine 
will contai n the server's response. ser_iine can also beused in other routines. 

handie_server_response decodes the response, which comesfrom the server on host . If the eli ent isauthorized, it returns 0. A 
client that isonly allowed to read isauthorized, but handie_server_response will print a messageon the standard output. If 
the client isnot authorized to talk to the server, a message isprinted, and the routine returns -1. 

put_server sendsthetext in b uff to the server, addi ng the necessary N NTP lineterminatorsand flushi ng the I/O buffer. 

get_server reads a line of text from the server into buf f , readingat mostbuff si ze characters. Any trailing \r\n termi nators 
are stri pped off. get_server returns -1 on error. 

ciose_server sends a quit command to the server and closes the connection. 
HI STORY 

W ritten by Rich $alz (rsaizuuunet.uu.net) for InterN etN ews. 
SEE ALSO 

libinn(3) 



clock 

clock— D etermine processor time 
SYNOPSIS 

#include <t ime . h> 
clock_t clock (void) ; 

DESCRIVO N 

Theciocko function returnsan approximation of processor timeused by the program. 
RETURN VALUE 

Thevaluereturned is the CPU timeused so far as a ciock_t; to get the num ber of secondsused, divide by clocks_per_sec. 
CONFO RMSTO 

ANSI C 

BUGS 

TheC standard allows for arbitrary valuesat the start of the program; takethedifferencebetween thevaluereturned from a 
cali to clock 0 at the start of the program and thevaluereturned at the end for maximum portability. 

Thetimeso function cali returns more information. 

SEE ALSO 

times(2) 

GNU, 21 Aprii 1993 



closedir 

closedir— C lose a di rectory 
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SYNOPSIS 

#include <sys/types.h> 
#include <dirent.h> 
int closedir(DIR *di r ) ; 

D ESC RIPTIO N 

Theciosediro function closes the directory stream associateci with di r . The directory stream descri ptor d r isnot available 
after thi scali. 

RETURN VALUE 

Theciosediro function returns 0 on success or -1 onfailure. 

ERRORS 

ebadf Invalid directory stream descriptor d r. 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3 

SEEALSO 

close(2), opendir(3), readdir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

11 Junel995 

confstr 

confstr— Get confi guration-dependent string variables 
SYNOPSIS 

#define _USE_POSIX_2 
#include <unistd.h> 

size_t confstr(int name, char *buf , sìze_t leu); 

DESCRIPTION 

confstr( ) gets the value of confi guration-dependent string variables. 

Thename argument isthe system variableto bequeried. Thefollowing variables are supported: 

cs_path A value for the path variablethat indi cateswhere ali the POSIX. 2 standard Utilities can befound. 

Ifbuf isnot NULL, and 1 en isnotO, confstro copies the value of the stri ng to buf truncated to len-1 charactersif necessary, 
with a nuli character as termi nation. Thiscan bedetected by compari ng the return value of confstro against 1 en. 

Iflen i S 0 an d b u f ÌSNULL, confstr)) just retumsthevalue in Return Value. 

RETURN VALUE 

If name does not correspond to a valid configuration variable, confstro returnso. 
EXAMPLES 

Thefollowing code fragment determi nes the path whereyou can find the POSIX. 2 system Utilities: 

char *pathbuf; size_t n; 

n = confstr(_CS_PATH,NULL,(size_t)0); 

if ((pathbuf = malloc(n)) == NULL) aborto; 

confstr (_CS_PATH, pathbuf, n); 




ERRO RS 

If thevalueof name isinvalid, ermo ÌSSettO EINVAL. 

CONFO RMSTO 

Propose) PO SIX.2 

BUGS 

POSIX.2 isnot yet an approvai standard; theinformation in this man page is subject to change. 
SEEALSO 

sh(l), exec(2), system(3) 

GNU, 17 Aprii 1993 

copysign 

copysign— Copiesthesign of anumber 
SYNOPSIS 

#include <math.h> 

doublé copysign(double x, doublé y); 

DESCRIVO N 

Theco pysigno function returns a value whose absolute value matches x , butwhosesign matchesthatofy. 
CONFO RMSTO 

BSD 4.3 

GNU, 6 junel993 

cos 

cos— Cosinefunction 
SYNOPSIS 

#include <math.b> 
doublé cos(double x ) ; 

DESCRIPTION 

The coso function returnsthecosineof x, wherex isgiven in radians. 

RETURN VALUE 

The coso function returnsavaluebetween -1 and 1. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acos(3), asin(3), atan(3), atan2(3), sin(3), tan(3) 

8 Junel993 
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cosh 

costi— H yperbolic cosinefunction 
SYNOPSIS 

#include <math.h> 
doublé costi (doublé x ) ; 

D ESC RIPTIO N 

Thecosho function returns the hyperbolic cosine of x, which isdefined mathematically as <exp(x)+exp(-x))/2. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acosh(3), asinh(3), atanh(3), sinh(3), tanh(3) 

13 Junel993 



crypt 

crypt— Password and data encryption 
SYNOPSIS 

#include <unistd.h> 

char *crypt(const char * k e y , const char *salt); 

DESCRIPTION 

crypt isthepassword-encryption function. It isbased on the Data Encryption Standard algorithm, with variations intended 
(among other things) to discourage the use of hardware im pi ementati ons of a key search. 

key isauser'styped password. 

sai t isatwo-character stri ng chosen from the set [a-zA-zo-9./]. Thisstring isused to perturb the algorithm in oneof 4,096 
different ways. 

By taking the lowest seven bitsof each character of the key, a 56-bit key is obtai ned. T his 56-bit key isused to repeatedly 
encrypt a Constant stri ng (usually a stri ng consisti ng of ali os). Thereturned valuepointsto theencrypted password, a series 
of 13 pri ntabl e ASC 1 1 characters (with thefirsttwo characters representi ng the salt itself). The return valuepointsto stati c 
datawhosecontent isoverwritten byeach cali. 

W arni ng: The key space consistsof equal 7.2ei6 possi blevalues. Exhaustivesearchesof thiskey space are possi ble usi ng 
massi vely parallel computers. Software, such ascrack(l), isavailableto search the porti on of thiskey space that is general ly 
used by humansfor passwords. H enee, password selection should, at minimum, avoid common wordsand names. U si ng a 
passwd(l) program that checksforcrackable passwords duri ng the selection processisrecommended. 

TheD ES algorithm itself hasafew qui rks that makeusing thecrypt(3) interface a very poor choicefor anything other than 
password authentication. If you are planning to usethecrypt(3) i nterfacefor a cryptography project, don't do it; getagood 
book on encryption and oneof the widely avai lable D ES li braries i nstead. 

C0NF0RMST0 



SVID, X/OPEN, BSD 4.3 



astimi dime, gmtime, locai ti me mktime 



SEEALSO 

login(l), passwd(l), encrypt(3), getpass(3), passwd(5) 

3 September 1994 

ctermid 

ctermid— Gets control li ng terminal name 
SYNOPSIS 

(finclude <stdio.h> 
char *ctermid(char *s ) ; 

DESCRIPTION 

ctermid o returns a string that isthepathnameforthecurrent control li ng terminal forthis process. If s ìsnull, a stati c buffer 
isused; otherwise, s pointsto a buffer used to hold the terminal pathname. The symbol ic Constant i__ctermid isthe 
maximum numberofcharactersinthereturned pathname. 

RETURN VALUE 

Thisfunction returns the pointer to the pathname. 

C0NF0RMST0 

POSIX.l 

BUGS 

Thepath returned might not uniquely identify the control li ng terminal; it might, for example, be/dev/tty. 
It isnotassured that the program can open theterminal. 

SEEALSO 

ttyname(3) 

GNU, 6 Apri 1 1993 

asctime, ctime, gmtime, localtime, mktime 

asctime, ctime, gmtime, localtime, mktime— T ransform binary date and ti me to ASC II 
SYNOPSIS 

#include <time.h> 

char *asctime(const struct tm "timeptr); 
char *ctime(const time_t *t i me p ) ; 
struct tm *gmtime(const time_t *t i me p ) ; 
struct tm *localtime(const time_t *timep); 
time_t mktime (struct tm *t i me p t r ) ; 
extern char *t z na me [2] ; 
long int t i me z o n e ; 
extern int day! i ght ; 

DESCRIPTION 

Thectimeo, gmtimeo, and iocaitime( (functions ali takean argumentof datatypetimet, which representscalendartime. 
When interpreted asan absolutetimevalue, it representsthenumber of secondselapsed since00:00:00 on January 1, 1970, 
Coordinated Universal Time (UTC). 
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Theasctimeo and mktimeo functions both takean argument representing broken-down time, which isa binary representa- 
tion separated into year, month, day, and so on. Broken-down time isstored in the structure tm, which isdefined in <time.h> 
asfollows: 

struct tm 
{ 

int tm_sec; /* seconds */ 

int tm_min ; /* minutes */ 

int tm_hour; /* hours */ 

int tm_mday ; /* day of the month */ 

int tmjnon; /* month */ 

int tm_year; /* year */ 

int tm_wday; /* day of the week */ 

int tm_yday; /* day in the year */ 

int tm_isdst; /* daylight saving time */ 

}; 



The members of thet m structure are 



tm_sec 


Thenumber of seconds after the minute, normally in therangeO to 59, but can beup to 61 to allow for 
leap seconds. 


tm_min 


Thenumber of minutes after the hour, in therangeO to 59. 


tm_hour 


Thenumberof hours past midnight, in therangeO to 23. 


tm_mday 


The day of the month, in therangelto 31. 


tm_mon 


Thenumberof monthssincejanuary, intherangeOto 11. 


tm_year 


The number of years si nce 1900. 


tm_wday 


Thenumberof dayssinceSunday, in therangeO to 6. 


tm_yday 


Thenumberof dayssincejanuary 1, in therangeO to 365. 


tm_isdst 


A flag that i ndicates whether daylight savingstimeis in effect at the time described. The valueis positive if 
daylight saving time is in effect, 0 if it isnot, and negative if the information isnot available. 



Thectimeofunction convertsthecalendartimet i mep into astringof theform 

"Wed Jun 30 21 :49:08 1993\n" 



Theabbreviationsforthedaysof theweek aresun, Mon , Tue, wed, Thu, Fri, and sat. Theabbreviationsforthemonthsare 
Jan, Feb, Mar, Apr, May, jun, jui, Aug, sep, Oct, nov, and Dee. The return value points to a statically allocated string that might 
beoverwritten by subsequent Calisto any of the date and ti me functions. The function also setstheexternal variabletzname 
with information aboutthecurrenttimezone 

Thegmtimeo function convertsthecalendartimetimepto broken-down timerepresentation, expressed in Coordinated 
Universal Time(UTC). 

Theiocaitimeo function converts the calendar ti met i mep to broken-ti me representati on, expressed relative to theuser's 
specified ti me zone. The function setstheexternal variablestzname with information aboutthecurrenttimezone, ti me z o n e 
with thedifferencebetween Coordinated U ni versai Ti me and locai standard time in seconds, anddayii jht to a nonzero 
value if standard U .S. daylight savingtimerulesapply. 

Theasctimeo function converts the broken-down ti me value ti meptr into a string with the same format asctimeo. The 
return value poi ntsto a statically allocated string that might beoverwritten by subsequent Calisto any of the date and time 
functions. 

The mktimeo function converts a broken-down ti me structure, expressed as locai time, to calendar timerepresentation. The 
function ignores the specified contentsof the structure members tm_wday and tm_yday and recomputesthem from theother 
information in the broken-down ti me structure. Calling mktimeo also setstheexternal variabletzname with information 
aboutthecurrenttimezone. If the specified broken-down timecannot be represented as calendar time, mktimeo returnsa 
value of (time_t)(-i) and does not alter thet m_ wday and t m_yday membersof the broken-down timestructure 



div 




CONFORMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

date(l), gettimeofday(2), time(2), tzset(3), dif f time(3), strftime(3), newctime(3) 

BSD, 26 Aprii 1996 

difftime 

difftime— C alculates time difference 
SYNOPSIS 

#include <t ime . h> 

doublé dif f time (timejt ti mei, time_t ti me 0 ) ; 

D ESC RIPTIO N 

The difftime o function returnsthenumber of seconds elapsed between timet i mei and timet i meo. Thetwo timesare 
specified in calendar time, which represents the ti me elapsed since 00:00:00 onjanuary 1, 1970, Coordinated Universal 
Time(UTC). 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

date(l), gettimeofday(2), time(2), ctime(3), gmtime(3), localtime(3) 

GNU, 2 July 1993 

div 

div— C omputes the quoti ent and remainder of integer di vision 
SYNOPSIS 

#include <stdlib.h> 

div_t div(int ri u me r , int denom); 

DESCRIPTION 

The divo function computes the valuenu me n denom and returnsthequotient and remainder in a structure named div_t that 
containstwo integer members named quot andrem. 

RETURN VALUE 

Thediv_t structure. 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

ldiv(3) 

6 Junel993 
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drand48, erand48, lrand48, nrand48, mrand48, j rand48, srand48, 
seed48, lcong48 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48— G enerate uniformly distri buted pseudo- 

random numbers 
SYNOPSIS 

#include <stdlib.h> 
doublé drand48(void) ; 

doublé erand48(unsigned short int xsubi [3]); 
long int lrand48(void) ; 

long int nrand48(unsigned short int xsubi [3]); 
long int mrand48(void) ; 

long int jrand48(unsigned short int xsubi [3]); 
void srand48(long int seedval ); 

unsigned short int * seed48(unsigned short int seedUv [3]); 
void lcong48(unsigned short int p a r a m[ 7J ) ; 

D ESC RIFTIO N 

These functions generate pseudo-random numbers using the linear congruenti al algorithm and 48-bit integer arithmetic. 

Thedrand48() and erand48() functions return non-negative double-precision floating-point values uniformly di stri buted 
between [0.0, 1.0]. 

Theirand48() and nrand48() functions return non-negati ve long integers uniformly di stri buted between 0 and 2~31. 
Themrand48() and jrand48() functions return signed long integers uniformly distri buted between -2^31 and 2^31. 
Thesrand48(),seed48(), and icong48() functions are initi alization functions, oneof which should becalled beforeusing 

drand48(), lrand48(), Or mrand49( ) . The functÌ0nSerand48( ) , nrand48(), and jrand48() do not requirean initialization 

function to becalled first. 

Ali the functions work by generati ng a sequenceof 48-bit integers, Xi, accordi ngto thelinear congruenti al formula 
Xi+l=(aXi+c) modm, wherei >=0 

Theparameter m=2-48; hence48-bit integer arithmetic isperformed. U nlessicong48() iscalled, a and care given by 

a = 0X5DEECE66D 
c = 0xB 

Thevaluereturned by anyof the functions drand48(), erand48(), irand48(), nrancMso, mrand48(), or jrand48() iscomputed 
by fi rst generati ng the next 48-bit x i n the sequence. T hen the appropriate number of bits, accordi ng to the type of data 
item to bereturned, iscopied from the high-order bits of x i and transformed into thereturned value. 

Thefunctionsdrand48(), irand48(), and mrand48() store the last 48-bit xì generated in an internai buffer. The functions 
erand48(), nrand48(), and jrand48() requi re the calli ng program to provide Storage for the successivexi values in the array 
argument xsubi . The functions are initi al ized by piaci ng the initial value of x into the array before calli ng the function for 
the fi rst ti me. 

The initializer function srand48() setsthe high-order 32 bits of xì to the argument seedva .Thelow-orderl6 bits are setto 
the arbitrary value 0x330E. 

The initializer function seed48() sets the value of xì to the 48-bit value specifi ed in the array argument seedl6v. The 
previ ous vai ueofXi iscopied into an internai buffer and a pointer to this buffer isreturned by seed48(). 

The initialization function icong48() allowstheuserto specify initial values for x , a and c. Array argument elements 
param[0-2] specifyxi , param[3-5] specify a , and param[6] specifi esc. After icong48() hasbeen called, asubsequentcall to 
either srand48() orseed48() will restore the standard values of a andc. 



ecvt, fcvt 



CONFORMSTO 

SVID 3 

NOTES 

Thesefunctionsaredeclared obsolete by SVID 3, which statesthatrand(3) should beused instead. 
SEEALSO 

rand(3), random(3) 

2 July 1993 

drem 

dreni— Floating-poi nt remainder function 
SYNOPSIS 

#include <math.h> 

doublé drem(double x, doublé y); 

DESCRIPTION 

Thedremo function computes the remai nder of dividing x by y . The return valueisx-n*y, wheren isthequotient of x 
divided by y, rounded to thenearest integer. If thequotient \sY2, it isrounded to theeven number. 

RETURN VALUE 

Thedremo function returns the remainder unlessy isO, in which case the function fai Is and ermo is set. 
ERRORS 

edom Thedenominatory isa. 

CONFORMSTO 

BSD 4.3 

SEEALSO 

fmod(3) 

6 Junel993 

ecvt, fcvt 

ecvt, fcvt— Convert a floating-poi nt number to astring 
SYNOPSIS 

#include <stdlib.h> 

char *ecvt (doublé n u mb e r , size_t nd i g i t s , int*d e c pt , int*s i gn ) ; 
char *fcvt( doublé number , size_t nd i g i t s , int*d ec pt , int*s i g n ) ; 

DESCRIPTION 

T he ecvt o function converts number to a NuiL-terminated stringof ndi gì t s digitsand returns a pointer to the stri ng. The 
string itself doesnot contai n a decimai point; however, theposition of the deci mal point relative to the start of the stri ng is 
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stored in decpt . A negative valuefordecpt meansthat the deci mal point isto theleft of the start of the stri ng. If thesign of 
number is negative, s i g n is set to a nonzero value; otherwise, it's set to 0. 

Thetcvto function isidentical to ecvto, except that n d gi t s specifies the number of di gits after the decimai point. 
RETURN VALUE 

Both the ecvto and fcvto functions return a pointer to a stati c stri ng contai ni ng the ASC II representati on of number .The 
stati c stri ng isoverwritten by each cali to ecvto or fcvto. 

SEEALSO 

gcvt(3), sprintf(3) 

28 M arch 1993 



erf,erfc 

ert, erte— Errar function and complementary errar function 
SYNOPSIS 

#include <math.h> 
doublé erf (doublé x ) ; 
doublé erte (doublé x ) ; 

DESCRIPTION 

The erf 0 function returns the errar function of x, defined as 

erf(x) = 2/sqrt(pi)* integrai froni 0 to x of exp(-t*t) dt 

Theerfco function returns the complementary error function of x — that is, l.O-erf(x). 
C0NF0RMST0 

SVID 3, BSD 4.3 

SEEALSO 

exp(3) 

BSD, 25 junel993 



execl, execlp, execle, exect, execv, execvp 

execl, execlp, execle, exect, execv, execvp— Execute a file 

SYNOPSIS 

#include <unistd.h> 
extern char ""environ; 

int execl(const char *path, const char *arg, ...); 
int execlp(const char *f i I e , const char "arg, ...); 
int execle(const char "patti, const char "arg, ...); 
int execlp(const char *f i I e , const char "arg, ...); 
int execle(const char *path, const char "arg, ...); 

int execle(const char *path, const char "arg , char * const e n v p [ ] ) ; 

int exect(const char * p a t h , char "const argv []); 
int execv(const char * p a t h , char "const a r g v [ ] ) ; 
int execvp(const char "file, char "const a r g v [ ] ) ; 



execl, execlp, execle, exect, execv, execvp 



DESCRIPTION 

Theexec family of functions replaces the current processi magewith a new processi mage. Thefunctionsdescribed in this 
manual page are front endsforthefunction execve(2). (Seethemanual pagefor execve for detailed informati on about the 
replacement of the current process.) 

Theinitial argument for these functions is the pathnameof a file that isto beexecuted. 

Theconst char *arg and Subsequent ellipses in theexecl, execlp, and execle functionscan bethought Of aSargB, argl, ... , 

argn. Togethertheydescri bea list of oneor more pointersto nul I-termi nated stri ngs that represent the argument list 
availableto theexecuted program. The first argument, by convention, should point to thefilenameassociated with the fi le 
being executed. The list of arguments must beterminated by a min pointer. 

The exect, execv, and execvp functions provi de an array of pointersto null-termi nated stri ngs that represent the argument 
list availableto thenew program. The first argument, by convention, should pointto thefilenameassociated with thefile 
being executed. T he array of pointers must beterminated by snull pointer. 

The execle and exect functions also specify theenvironment of theexecuted process by following theNULL pointer that 
termi nates the listof arguments in theparameter list or the pointer to theargv array with an additional parameter. This 
additional parameter isan array of pointersto nul I-termi nated stri ngs and must beterminated by aNULL pointer. Theother 
functions take theenvironment for the new process imagefrom theexternal vari able e n v i ron in thecurrent process. 

Some of these functions have special semantica 

The functions execip and execvp will duplicate the actionsof theshell in searchingfor an executable fi le if thespecified 
filenamedoesnot contai n aslash (/) character. Thesearch path isthepath specified in theenvironment by thePATH vari able. 
If this vari able isn't specifi ed, the default path /bin:/usr/t>in: isused (isthistrue for Linux?). In addition, certain errorsare 
treated speci al ly. 

If permi ssion isdenied for a file (theattempted execve returned eacces), these functions will conti nuesearching the rest of 
thesearch path. If no other fileisfound, however, they will return with theglobal vari able ermo setto eacces. 

If theheaderof a fi le isn't recognized (theattempted execve returned ENOEXEC), these functions will execute theshell with 
the path of the file as its fi rst argument. (If this attem pt fails, no further searching is done.) 

If the file iscurrently busy (theattempted execve returned etxtbusy), these functions will sleep for several seconds, periodi- 
cai ly re-attempting to execute the fi le. (Isthistrue for Linux?) 

Thefunction exect executesafilewith the program-tracing faci I iti esenabled (seeptrace(2)). 
RETURN VALUES 

If anyof theexec functions returns, an error will have occurred. The return value is -1, and theglobal variableerrno will be 
setto indicate the error. 

FILES 

/bin/sh 

ERRORS 

execi, execie, execip, and execvp may fail and set ermo for any of theerrors specified for the library functions execve(2) and 

malloc(3). 

exect and execv may fail and set ermo for any of theerrors specified for the library function execve(2). 
SEE ALSO 

sh(l), execve(2), fork(2), trace(2), environ(5), ptrace(2) 

COMPATIBILITY 

H i stori cai ly, the default path for the execip and execvp functions was /bin:/usr/bin.Thiswaschanged to place the current 
directory last to enhance system security. 
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Thebehavior of execip and execvp when errorsoccur whileattempting to execute the file is historic practice, but has not 
traditionally been documentai and isnotspecified bythePOSIX standard. 

Traditionally, the functions execip and execvp ignored ali errorsexceptfortheonesdescribed aboveand enomem and e2big, 
upon which they returned. They now return ifany errar other than theonesdescribed in the'Trrors" section occurs. 

STANDARD S 

execl, execv, execle, execip, and execvp COnform tO IEEE Stdl003.1-88 (POSIX.l). 

BSD M an Page, 29 N ovember 1993 

ermo 

ermo— N umber of last errar 
SYNOPSIS 

#include <errno.h> 
extern int ermo; 

D ESC RIPTIO N 

Theinteger ermo i s set by system calls (and some library functions) to indicatewhatwentwrong. I ts value is significant only 
when the cali returnsan errar (usually-1), and a library function that doessucceed isallowed to changeerrno. 

Sometimes, when -1 i s al so a I egal return value, you haveto set ermo to 0 before the cali in order to detect possi bleerrors. 

POSIX lists the following symbolic errar names: 



E2BIG 


Arg listtoo long 


EACCES 


Permission denied 


EAGAIN 


Resource tempo rarily unavailable 


EBADF 


Bad filedescri ptor 


EBUSY 


Resource busy 


ECHILD 


Nochild processes 


EDEADLK 


Resource deadlock avoided 


EDOM 


Domain errar 


EEXIST 


Fileexists 


E FAULT 


Bad address 


EFBIG 


Filetoo large 


EINTR 


Interrupted function cali 


EINVAL 


Invalid argument 


EIO 


Input/output errar 


EISDIR 


Isa directory 


EMFILE 


Too many open files 


EMLINK 


Too many links 


ENAMETOOLONG 


Filenametoo long 


ENFILE 


Too many open files in system 


ENODEV 


N 0 such device 


ENOENT 


Nosuch fi le or directory 


ENOEXEC 


Exec format errar 


ENOLCK 


N 0 locksavailable 


ENOMEM 


N ot enough space 



exp, log, loglO, pow 



ENOSPC 

ENOSYS 

ENOTDIR 

ENOTEMPTY 

ENOTTY 

ENXIO 

EPERM 

EPIPE 

ERANGE 

EROFS 

ESPIPE 

ESRCH 

EXDEV 

SEEALSO 

perror(3) 



N o space left on device 
Function not implemented 
N ot a di rectory 
Directory not empty 
Inappropriate I/O control operation 
N o such device or address 
Operation not perni itted 
Broken pipe 
Resulttoo large 
Read-only filesystem 
Invalid seek 
N o such process 
Improper link 
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exit 

exit— Causes normal program termination 
SYNOPSIS 

#include <stdlib.h> 
void exit(int status); 

D ESC RIPTIO N 

Theexito function causes normal program termination, and thevalueof status isreturned to theparent. Ali functions 
regi stered with atexito and on exìto arecalled in the reverse order of their regi strati on, and ali open streamsareflushed 
and closed. 

RETURN VALUE 

Theexito function does not return. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

_exit(2), atexit(3), on_exit(3) 

GNU, 2 Aprii 1993 



exp, log, log1 0, pow 

exp, log, logie, pow— Exponenti al, logarithmic, and power functions 
SYNOPSIS 



#include <math.h> 
doublé exp(double x ) ; 



Part III: Library Functions 

doublé log(double x ) ; 

doublé log10(double x ) ; 

doublé pow(double x, doublé y); 

D ESC RIPTIO N 

The expo function returnsthevalueof e (the base of naturai logarithms) raised to the power of x. 
Theiogo function returns the naturai logarithm of x. 
Theiogi0() function returnsthebase-10 logarithm of x. 
Thepowo function returnsthevalueof x raised to the power ofy. 

ERRO RS 

Theiogo and logico functions can return thefollowingerrors: 

edom Theargumentx is negative. 

erange Theargumentx ise. The log of 0 is not defined. 

Thepowo function can return thefollowing errar: 

edom Theargumentx is negative and y isnot an integrai value. Thiswould result in acomplex number. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

sqrt(3), cbrt(3) 

GNU junel6, 1993 

expm1,log1p 

expmi, ìogip— Exponenti al minusl, logarithm of 1 plusargument 
SYNOPSIS 

#include <math.h> 
doublé expml (doublé x ) ; 
doublé loglp (doublé x ) ; 

DESCRIPTION 

expmi (x ) returns a value equi valent to exp (x)-l. It iscomputed in away that is accurate even if the value of x isnear 0— a 
casewhereexp (x)-l would be inaccurate due to subtraction of two numbers that are nearly equal. 

iogip(x ) returnsa value equivalentto log (1 +x). It iscomputed in away that is accurate even if the value of x isnearO. 
C0NF0RMST0 

BSD 

SEEALSO 

exp(3), log(3) 

GNU, 16 September 1995 



fabs 

F abs— A bso I ute vai u e of f I oati n g- po i n t n um ber 
SYNOPSIS 

#include <math.h> 
doublé fabsfdouble x ) ; 

DESCRIVO N 

The f abs( ) function returns the absolute value of the fi oati ng-point number x 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

abs(3), ceil(3), floor(3), labs(3), rint(3) 

foiose 

fciose— Closesastream 
SYNOPSIS 

(finclude <stdio.h> 
int fclose(FILE *stream); 

DESCRIPTION 

The foiose function dissociates the named st r eam from its underlyi ng fi le or set of functions. If thestream wasbeingused for 
output, any buffered data iswritten first, usingffiusn(3). 

RETURN VALUES 

U pon successful completion, 0 isreturned. Otherwise, eof isreturned, and theglobal variableerrno isset to indicate the 
error. I n either case, no further access to the stream is possi ble. 

ERRORS 

ebadf T he argument stream isnotan open stream. 

The foiose function may also fail and set ermo for any of the errors specified fortheroutinesciose(2) or ffiush(3). 
SEEALSO 

close(2), fflush(3), fopen(3), setbuf(3) 

STANDARD S 

Thefciose function conformstoAN SI C 3.159-1989 ("AN SI C"). 

BSD M an Page, 29 N ovember 1993 



clearerr, feof, ferrar, fileno 
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clearerr, feof, f error, fileno 

clearerr, feof, f error, fileno— Check and reset stream status 
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SYNOPSIS 

#include <stdio.h> 
void clearerr( FILE *stream); 
int f eof (FILE *s t r e a m) ; 
int ferror(FILE *s t r e a m ) ; 
int fileno(FILE *st ream) ; 

DESCRIPTION 

Thefunction ciearerr clears the end-of-fi le and errar indicatore for thestream pointed to byst ream. 

Thefunction teof tests the end-of-file i ndicator for the stream pointed to byst ream, returni ng nonzero if it i s set. Theend- 
of-fileindicatorcan only becleared by thefunction ciearerr. 

Thefunction terror tests the error i ndicator for thestream pointed to byst ream, returni ng nonzero if it is set. The errar 
indicator can only be reset by the ciearerr function. 

Thefunction fileno examinestheargumentstream and returns its integer descriptor. 
ERRO RS 

T hese functions should notfail and do not set the extern al variableerrno. 
SEEALSO 

open(2), stdio(3) 

STANDARD S 

Thefunctionsciearerr, teof, and terror conform to C 3.159-1989 ("ANSI C"). 

BSD M an Page, 29 N ovember 1993 

f f lush, f purge 

ff ìush, fpurge— Flush a stream 
SYNOPSIS 

#include <stdio.h> 

int fflush( FILE "stream); 

int fpurge( FILE *st r eam) ; 

DESCRIPTION 

Thefunction ftiush forces a write of ali buffered data for the given output or update stream via the stream 'sunderlying write 
function. The open status of the stream isunaffected. 

If thestream argument ìsnull, ftiush flushes ali open output streams. (D oesthishappen under Linux?) 

Thefunction fpurge erasesany input or output buffered in the given stream. For output streams, thisdiscardsany unwritten 
output. For input streams, thisdiscardsany input read from the underlying object but notyet obtained viagetc(3); this 
includes any text pushed back via ungete. 

RETURN VALUES 

U pon successful completion, a isreturned. Otherwise, eof isreturned, and theglobal variableerrno is set to indicate the 
error. 

ERRORS 

ebadf Stream isnot an open stream, or, in the case off fiush, not a stream open for writing. 

Thefunction ftiush may also fail and set ermo for any of the errors specified for the routine write(2). 



fgetgrent 

BUGS 

Linux may not support fpurge. 
SEEALSO 

write(2), fopen(3), fclose(3), setbuf(3) 

STANDARD S 

TheffiushfunctionconformstoANSI C3. 159-1989 ("AN SI C"). 

BSD M an Page, 29 N ovember 1993 

ffs 

ffs— Finds first bit set in a word 
SYNOPSIS 

#include <string.h> 
int ffs(int i ) ; 

DESCRIPTION 

Thetfso function returns the position of the first bit set in the word . Theleast significant bit isposition 1, and themost 
significant position 32. 

RETURN VALUE 

Thetfso function returns the position of the first bit set, orNULL if no bits are set. 
C0NF0RMST0 

BSD 4.3 

GNU, 13 Aprii 1993 



fgetgrent 

fgetgrent— Gets group fi le entry 
SYNOPSIS 

#include <grp.h> 

#include <stdio.h> 

«include <sys/types.h> 

struct group *fgetgrent(FILE *s t r e a m ) ; 



DESCRIPTION 

The fgetgrent o function returns a pointer to a structure containing the group information from thefilestr eam. The first 
timeit iscalled it returns the first entry; thereafter, it returns successive entri es. The fi le s t rea m must have the same format as 

/etc/group. 

The group structure is defi ned in <grp.n> asfollows: 

struct group { 

char *gr_name; /* group name */ 

char *gr_passwd; /* group password */ 

gid_t gr_gid; /* group id */ 

char **gr_mem; /* group members */ 

>; 
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RETURN VALUE 

Thefgetgrentofunction returnsthegroup information structure, orNULL if thereareno m ore entri es or an erroroccurs. 
ERRORS 

enomem Insufficient memory to allocate group information structure. 

CONFO RMSTO 

SVID 3 

SEEALSO 

getgrnam(3), getgrgid(3), getgrent(3), setgrent(3), endgrent(3) 

G N U , 4 Aprii 1993 

fgetpwent 

fgetpwent— Gets password fi le entry 
SYNOPSIS 

#include <pwd.h> 

#include <stdio.h> 

#include <sys/types.h> 

struct passwd *fgetpwent ( FILE *stream); 

DESCRIPTION 

The fgetpwent o function returns a pointer to a structure containing the broken-out fields of a line in the fi les t r e a m. The 
first ti mei t i s cai I ed it returns the first entry; thereafter, it returns successive entries. T he fi le s t rea m must havethesame 

format as/etc/passwd. 

Thepasswd structure is defined in <pwd.h> asfollows: 

struct passwd { 



char 


*pw_name; 


/* 


username */ 


char 


*pw_passwd; 


/ * 


user password */ 


uid_t 


pw_uid; 


/* 


user id */ 


gid_t 


pw_gìd; 


/* 


group id */ 


char 


*pw_gecos; 


/ * 


real name */ 


char 


*pw_dir; 


/* 


home directory */ 


char 


*pw_shell; 


/* 


shell program */ 



}; 

RETURN VALUE 

The fgetpwent o function returns the passwd structure, or null if thereareno more entries or an erroroccurs. 
ERRORS 

enomem Insufficient memory to allocate passwd structure. 

FI LES 

/etc/passwd password databasef ile 



C0NF0RMST0 

SVID 3 



fmod 



SEEALSO 

getpwnam(3), getpwuid(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwent( 3), passwd(5) 

GNU, 17 May 1996 

floor 

fioor— Largest integrai value not greater than x 
SYNOPSIS 

#include <math.h> 
douPle floor (doublé x ) ; 

DESCRIPTION 

Thetiooro function roundsx downwardto thenearest integer, returni ngthat value as a doublé. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

abs(3), fabs(3), ceil(3), rint(3) 

6 Junel993 

fmod 

fmod— Floating-point remainder function 
SYNOPSIS 

#include <math.h> 

doublé fmod(double x, doublé y); 

DESCRIPTION 

Themodfo function computesthe remainder of dividi ng x by y . The return value isx-n*y, wheren isthe quotient of x/y, 
rounded toward 0 to an integer. 

RETURN VALUE 

T he fmod o function returns the remainder unlessy isO, in which case the function fai Is and ermo is set. 
ERRORS 

edom Thedenominatory isO. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

drem(3) 

6 Junel993 
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fnmatch 

f rimateti— M atches filmarne or pattinarne 
SYNOPSIS 

#include <f nmatch . h> 

int f nmatch(const char 'pattern, const char *strings,int flags); 

D ESC RIPTIO N 

fnmatch o checksthest r i ngs argument and checks whether it matches the pat t e r n argument, which isashell wildeard 
pattern. 

Thefi ags argument modifies the behavior; it isthe bitwiseoR of zero or moreof thefollowing flags: 

fnm_noescape If thisflag is set, treat backslash asan ordinary character instead of asan escape character. 

fnm_pathname If thi s flag is set, match aslash in stri ng onlywith aslash in pattern and not, forexample, with 

au - sequencecontaining aslash. 
fnm_period If thisflag isset, a leading period in st ri ng hasto bematched exactly by a period in pattern. A 

period isconsidered to be leading if it isthe first character in stri n g , or if both fnm_pathname is 

set and the period immediately follows a slash. 

RETURN VALUE 

Zero if stri ng matches pat t e r n , fnm_nomatch if there is no match, or another value if thereisan errar. 

C0NF0RMST0 

ProposedPOSIX.2 

BUGS 

POSIX.2 is not yet an approved standard; theinformation in thisman page is subject to change 
SEEALSO 

sh(l), glob(3), glob(7) 

GNU, 19 Aprii 1993 



f open, f dopen, f reopen 

fopen, fdopen, f reopen— Stream open functions 



SYNOPSIS 

#include <stdio.h> 

FILE *fopen( char *path, char *mode); 

FILE *fdopen ( int fi I d e s , char "mode ) ; 

FILE *freopen( char *path, char "mode ,FILE*st r eam) ; 

DESCRIPTION 

Thefopen function opensthefilewhosenameisthestring pointed to by path and associates a stream with it. 

The argument mode pointsto a stri ng beginning with oneof thefollowing sequences (addi ti onal characters may follow these 
sequences): 

r Open text fi le forreading. The stream ispositioned at the beginning of thefile. 

r+ Open for reading and writing. The stream ispositioned at the beginning of thefile 



fpathconf, pathconf 




w Truncatefileto zero length or create a text file for writing. The stream is positioned atthe 

beginningof thefile. 

w+ Open for reading and writing. Thefile iscreated if it does not esci st; otherwise it istruncated. 

Thestream ispositioned atthe beginningof thefile. 
a Open for writing. The fi le iscreated if it does not exi st. Thestream is positioned atthe end of 

thefile. 

a+ Open for reading and writing. Thefile iscreated if it does not exi st. Thestream ispositioned at 

the end of thefile. 

The mode stringcan also include the letter b eitherasathird characterorasacharacter between thecharacters in any of the 
two-character stringsdescribed previously. This is stri ctly for compati bility with AN SI C 3.159-1989 (AN SI C) and hasno 
effect; theb isignored. 

Any created fileswill nave mode sjrusr|s_iwusr|sjrgrp|sjwgrp|sjroth|sjwoth (0666), asmodified by the process's 

umask value. (See umask(2).) 

Readsand writes may beintermixed on read/write streams in any order. N otethat AN SI C requires that a file positioning 
function intervene between output and input, unlessan input operati on encountersend-of-file. (If thiscondition isnot met, 
then a read isallowed to return the result of writes otherthan themost recent.) Theref ore it isgood practice(and indeed 
sometimes necessary under Linux) to put an fseek or fgetpos operati on between writeand read operati onson such a stream. 
This operati on may bean apparent no-op (as in fseek(. . ., bl, seek_cur)) called for itssynchronizing side effect. 

Thefdopen function associates a stream with the exi sting file descriptor, mdes. The mode of thestream must be compati ble 
with the mode of the fi le descriptor. The fi le descriptor is not duplicated. 

Thetreopen function opensthefilewhosenameisthestring pointed to by pat h and associates the stream pointed to by 
stream with it. The originai stream (if it exists) isclosed. The mode argument isused just as in thetopen function. The 
primary use of thetreopen function isto eh an ge th e f i I e assoc i ated with a standard text stream (stderr, stdin, or stdout). 

RETURN VALUES 

On successful completi on, fopen, tdopen, and treopen return a file pointer. Otherwise, null isreturned, and theglobal 
variableerrno issetto indicate the errar. 

ERRORS 

einval The mode provided to fopen, tdopen, or treopen wasinvalid. 

Thetopen, tdopen, and treopen functionsmay also fail and set ermo for any of the errors specified for the routine maiioc(3). 

Thetopen function may also fail and set ermo for any of the errors specified fortheroutineopen(2). 

Thetdopen function may also fail and set ermo for any of the errors specified fortheroutinetcnti(2). 

Thetreopen function may also fail and set ermo for any of the errors specified fortheroutinesopen(2), tciose(3) and 

fflush(3). 

SEE ALSO 

open(2), fclose(3) 

STANDARD S 

Thetopen and treopen functionsconform to AN SI C 3.159-1989 (AN SI C). Thetdopen function conformsto IEEE 
Stdl003.1-1988 (POSIX.l). 

BSD M an Page, 13 D ecember 1995 



fpathconf, pathconf 

fpathconf, pathconf— Get confi gurati on valuesforfiles 
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Part III: Library Functions 



SYNOPSIS 

#include <unistd.h> 

long fpathconf (int f il edes ,intname ) ; 

long pathconf (char *path, int n a me ) ; 

D ESC RIPTIO N 

fpathconf o gets a valuefor the configurati on option name for the open fi le descri ptor f i i edes . 
pathconf o gets a value for confi guration option nane for thefilename pat h. 

Thecorresponding macrosdefined in <unistd.h> are the minimum values; if an application wantsto take advantage of values 
that may change, a cali to fpathconf o or pathconf o can bemade, which may yield more liberal results. 

Setti ng name equal to oneof the followingconstantsreturns the following confi guration options: 

Returns the maximum number of linksto the fi le. If f i i edes or pat h refersto a directory, the 
value appliesto the whole directory. Thecorresponding macro ìs_posix_link_max. 
Returns the maximum length of aformatted input line, wheref i edes or pat h must referto a 
terminal. Thecorresponding macro ìs_posix_max_canon. 

Returns the maximum length of an input line, wheref i edes or pat h must referto a terminal. 
Thecorresponding macro ìs_posix_max_input. 

Returns the maximum length of a filename in the directory patti or fiiedes theprocessis 
allowed to create. Thecorresponding macro ìs_posix_max_. 
Returns the maximum length of a relative path name when patti orti i edes isthecurrent 
working directory. Thecorresponding macro ìs_posix_path_max. 

R etu rns the si zeof the pipe buffer, wheref i edes must referto a pipe or FI FO, and pat h must 
referto a FIFO .Thecorresponding macro ìs_posix_pipe_buf. 

Returns nonzero if thecnown(2) cali may not beused on this file If fi i edes or path refersto a 
directory, this appliesto ali files in that directory. Thecorresponding macro is 

_POS I X_CHOWN_RESTR ICTED . 

Returns nonzero if accessing filenames longer than _posix_name_max generates an errar. The 
corresponding macro ìs_posix_no_trunc. 

Returns nonzero if special character processi ng can bedisabled, wheref i edes or pat h must 
refer to a terminal. 



PC link max 



pc max canon 



PC MAX INPUT 



PC NAME MAX 



PC PATH MAX 



PC PIPE BUF 



PC CHOWN RESTRICTED 



PC NO TRUNC 



PC VDISABLE 



RETURN VALUE 

The limit isreturned, if oneexists. If the system does not havea limit for the requested resource, -1 isreturned, and ermo is 
unchanged. If thereisan errar, -1 isreturned, and ermo issetto reflect the nature of the errar. 

CONFO RMSTO 

POSIX.l. Fileswith name lengths longer than the value returned for name equal to _pc_name_max may exist in thegiven 
directory. 

Some returned values may be huge; they are not suitable for allocati ng memory. 
SEEALSO 

getconf(l), statfs(2), open(2), sysconf(3) 

GNU, 4 Aprii 1993 



fread, fwrite 

fread, fwrite— Binary stream input/output 



fgetpos, fseek, fsetpos, ftdl, rewind 




SYNOPSIS 

#include <stdio.h> 

size_t fread(void *ptr, size_t size, size_t nmemb ,FILE*st r eam) ; 
size_t fwrite(void *ptr, size_t size, size_t nmemb ,FILE*s t r eam) ; 

D ESC RIFTIO N 

Thefunction fread reads nmemb elementsof data, each size bytes long, from thestream pointed to by str eam, stori ngthem at 
the location given byptr. 

Thefunction fwrite writes nmemb elementsof data, each size bytes long, to thestream pointed to by st r eam, obtai ni ngthem 
from the location given by pt r . 

RETURN VALUES 

fread and fwrite return thenumber of itemssuccessfully read orwritten (that is, not thenumber of characters). If an error 
occurs, ortheend-of-fileisreached, the return value is a short item count(ore). 

fread does not disti nguish between end-of-fileand error, and callers must usefeof(3) and ferror(3) to determi ne whi eh 
occurred. 

SEEALSO 

feof(3), f error(3), read(2), write(2) 

STANDARD S 

T he functions fread and fwrite conform toANSI C 3.159-1989 ("ANSI C"). 

BSD M an Page, 17 M ay 1996 

frexp 

frexp— Convertsfloating-pointnumbertofractional and integrai components 
SYNOPSIS 

#include <math.h> 

doublé frexp (doublé x, int *exp); 

DESCRIPTION 

The frexp o function isused to split the number x into a normalized fraction and an exponentthat isstored in ex p . 
RETURN VALUE 

Thefrexpo function returnsthe normalized fraction. If theargumentx is not e, the normalized fraction is x timesapower 
of 2, and is always in the ranger (inclusive) to 1 (exclusive). If % is 0, the normalized fraction isO, and 0 isstored in exp. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

ldexp(3), modf(3) 

GNU,6Junel993 



fgetpos, fseek, fsetpos, f teli, rewind 

fgetpos, fseek, fsetpos, ftell, rewind— Reposition a Stream 
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SYNOPSIS 

#include <stdio.h> 

int f seek(FILE *st r eam, longo f f s et , int uh e ne e ) ; 

long ftell(FILE *st ream) ; 

void rewìnd(FILE *s t r e a m ) ; 

int fgetpos(FILE *s t r e a m , fpost *pos); 

int fsetpos(FILE *s t r e a m , fpost *pos); 



DESCRIVO N 

Thetseek function sets the fi le positi on indicator forthestream poi nted to byst ream. The new positi on, measured in bytes, 
isobtained by adding offset bytes to the positi on specified by whence. If whence isset to seek_set, seek_cur, or seek_end, the 
offset is relative to the start of the fi le, thecurrent position indicator, or end-of-file, respectively. A successful cali to thetseek 
function clears the end-of-file indicator forthestream and undoesanyeffectsof theungetc(3) function on thesamestream. 

T he t teli function obtains thecurrent valueof the fi le position indicator forthestream poi nted to byst ream. 

Therewind function sets the fi le position indicator forthestream pointedto by st r eam to the beginning of thefile. Itis 
equi vai ent to 

(void)fseek(stream, 0L, SEEK_SET); 

exceptthat the errar indicator forthestream isalso cleared. (Seeciearerr(3).) 

Thetgetpos and tsetpos functions are alternate interfaces equi valentto tteii and fseek (with whence setto seek_set), setting 
and stori ng thecurrent valueof the fi le offset into or from the object referenced by pos . On somenon-U N IX systems, an 
tpos_t object may be a complex object, and theseroutinesmight betheonly way to portably repositi on atext stream. 

RETURN VALUES 

The rewind function returns no value. U pon successful completion, tgetpos, fseek, and fsetpos return a, and fteii returns 
thecurrent offset. Otherwise, -1 isreturned, andtheglobal variableerrno isset to indicate the errar. 

ERRORS 

ebadf Thestream specified isnot a seekable stream. 

einval T he whence argument to fseek was not seek_set, seek_end, or seek_cur. 

The function tgetpos, tseek, fsetpos, and fteii might also fail and set ermo for any of theerrors specified fortheroutines 

fflush(3), fstat(2), lseek(2), and rrialloc(3). 

SEE ALSO 

lseek(2) 

STANDARD S 

Thetgetpos, fsetpos, fseek, fteii, and rewind functions conform toANSI C 3.159-1989 (ANSI C). 

BSD M an Page, 29 N ovember 1993 



ftime 

ftime— Returns date and time 
SYNOPSIS 



#include <sys/timeb.h> 

int ftirne(struct timeb *t p ) ; 




DESCRIPTIO N 

Return current date and ti me in t p, which isdeclared asfollows: 

struct timeb { 
time_t time; 
unsigned short millitm; 
short timezone; 
short dstflag; 

}; 

RETURN VALUE 

T his function alwaysreturnsa. 

NOTES 

Under Linux, thisfunction isimplemented in a compati bility library instead of in the kernel. 

C0NF0RMST0 

Version7, BSD 4.3 

Under BSD 4.3, this cali isobsoleted by gettimeofday(2). 
SEEALSO 

time(2) 

Linux, 24 J uly 1993 

ftok 

ttok— Converts a pattinarne and a project identifierto a System V IPC key 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

keyjt ftok (char *p a t h n a me , char proj); 

DESCRIPTIO N 

The function converts the pattinarne of an existing accessi ble fi le and a project identifier into a key_t type System V IPC key. 
RETURN VALUE 

On success, the return valuewill betheconverted key_t value; otherwiseitwill be-1, with ermo indicatingtheerrorasfor 
thestat(2) system cali. 

BUGS 

Thegenerated key__t value isobtai ned by stating the disk fi le corresponding to pat h r a me in orderto getitsi-nodenumber 
and the minor device number of thefilesystem on which the disk file resi des, then by combini ng the 8-bit p r oj value along 
with thelowerl6 bitsof the inode number with the8 bitsof the minor devi ce number. The algorithm doesnot guaranteea 
unique key value. In fact, 

■ Two different nameslinkingto the same fi le produce the same key values. 

■ Using thelower 16 bitsof the i-node number gives some chance (although usuai ly small) to have the same key values 
for fi lenames referri ngto different inodes. 

■ N ot discriminating among major device numbers gives some chance of collision (also usually small) for systems with 
multi pie disk controllers. 
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SEEALSO 

ipc(5), msgget(2), semget(2), shmget(2), stat(2) 

Linux 0.99.13, 1 N ovember 1993 

ftw 

ftw— Filetreewalk 
SYNOPSIS 

#include <ftw.h> 

int ftwfconst char 'directory, 

int(*f uncpt r ) (const char «file, struct stat *s b , int f I ag ) , int dept h ) ; 

D ESC RIPTIO N 

ftwo walksthrough the directory tree, starti ngfrom the indicateci directory. For each found entry in the tree, it cai I s f uncpt r 
with the full pathnameof the entry relative to d ree tory, a pointer to thestat(2) structure for the entry and an int whose 
valuewill beoneof thefollowing: 

ftw_f Item is a normal file 

ftw_d Item is a directory 

ftw_ns The stat failecl on the item 

ftw_dnr Item isa directory which can't be read 

Warning: Anything other than directories, such assymbolic links, getstheFTW F tag. 

ftwo recursively calls itself for traversing found directories. To avoid using up ali a program's file descri ptors, dept h specifies 
thenumber of simultaneousopen directories. When thedepth isexceeded, ftwo will becomeslower because directories have 
to beclosed and reopened. 

To stop the tree walk, f uncpt r returns a nonzero value; this valuewill become the return valueof ftp(). Otherwise, ftwo will 
continue unti I it hastraversed the enti re tree (in which case it will return 0), or until it hitsan errar such asamaiioc(3) 
failure, in which case it will return -1. 

Because ftp 0 usesdynamic data structures, theonly safeway to exit a tree walk isto return a nonzero value. To handle 
interrupts, forexample, mark that the interrupt occurred and return anonzero value— don't useiongjmp(3) unlessthe 
program isgoingto terminate. 

SEEALSO 

stat(2) 

Linux, 18 July 1993 

gcvt 

gcvt— C onverts a floati ng-poi nt number to a stri ng 
SYNOPSIS 

«include <stdlib.h> 

char *gcvt(double number , size_t ndi gi t , char *buf ) ; 

DESCRIPTION 

The gcvt 0 function converts number to a minimal-length, N U LL-terminated ASCII stri ng and storestheresult in buf . It 
produces nd gi t significantdigits in either printf 0 F format or E format. 



getdirentries 



RETURN VALUE 

Thegcvto function returns the address of the stri ng pointed to by buf . 
SEEALSO 

ecvt(3), f cvt(3), sprintf(3) 

29 M arch 1993 



getcwd, get_current_dir_name, getwd 

getcwd, get_current_dir_name, getwd— Get Current working directory 



SYNOPSIS 

#include <unistd.h> 
char *getcwd(char *b u f , size_t si z e ) ; 
char *get_current_working_dir_name(void) ; 
char *getwd(char *buf ) ; 

DESCRIVO N 

The getcwd o function copies the absolute pathnameof the current working directory to thearray pointed to by buf , which is 
of length si ze. 

If the current absolute pathnamewould requirea buffer longer than si ze elements, null isreturned, and ermo isset to 
erange; an application should check forthi serrar, and allocate a larger buffer if necessary. 

Asan extension to thePOSIX.l standard, getcwd o al locates the buffer dynamically usingmaiioco if buf is null on cali. In 
th i s case, theallocated buffer has the length si ze unless s ze islessthan 0, when buf is allocateci aslargeas necessary. It is 
possi ble (and, indeed, advisable) to free the buffers if they nave been obtained thisway. 

get_current_dir_name, which isonly prototyped if use_gnu isdefined, will maiioc(3) an array big enough to hold the 

current directory name. If the environment vari ablepwD isset, and its value is correct, that valuewill bereturned. 

getwd, which isonly prototyped if use_bsd isdefined, will not maiioc(3) any memory. The buf argument should bea 

pointerto an array at least path_max bytes long, getwd returns only the first path_max bytesof theactual pathname. 

RETURN VALUE 

null on failure (for example, if the current directory isnot readable), with ermo set accordingly, and buf on success. 
CONFO RMSTO 

POSIX.l 

SEEALSO 

chdir(2), free(3), malloc(3). 

GNU, 21 July 1993 



getdirentries 

getdirentries— Gets directory entries in afilesystem-independentformat 
SYNOPSIS 

#define _USE_BSD or #define _USE_MISC 
#include <dirent.h> 

ssize_t getdirentriesfint f d , char *buf , size_t nbytes ,offt * b a s e p ) ; 
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DESCRIVO N 

Thisfunction reads directory entriesfrom the directory specified by f d into buf . At most, nbytes areread. Reading starts at 
offset *basep, and nasep isupdated with thenew position after reading. 

RETURN VALUE 

getdirentries returnsthenumber of bytesread, or a when at the end of the directory. If an error occurs, -1 isreturned, and 
ermo is set appropriately. 

ERRORS 

See the Linux library source codefor details. 
SEEALSO 

open(2), lseek(2) 

BSD /MISC, 22 July 1993 

getenv 

getenv— Getsan environment variable 
SYNOPSIS 

#include <stdlib.h> 

char *getenv(const char *name); 

DESCRIPTION 

The getenv o function searches the environment listfor astring that matches the stri ng pointed to byname. The stri ngs are of 

theform name=val uè . 

RETURN VALUE 

Thegetenvo function returns a pointer to the value in the environment, or null if thereisno match. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

putenv(3), setenv(3), unsetenv(3) 

GNU, 3 Apri 1 1993 

getgrent, setgrent, endgrent 

getgrent, setgrent, endgrent— G et group file entry 

SYNOPSIS 

#include <grp.h> 
#include <sys/types.h> 
struct group *getgrent(void) ; 
void setgrent(void) ; 
void endgrent(void) ; 



getgrnam, getgrgid 




DESCRIVO N 

Thegetgrento function returns a pointer to a structure contai ni ng thegroup informati on from /etc/group. The first timeit 
iscalled it returns the first entry; thereafter, it returns successive entri es. 

The setgrent ( ) function rewinds the fi le poi nter to the beginning of the /etc/group file. 

Theendgrent() function Closes the /etc/group file. 

Thegroup structure is defi ned in <grp.h> asfollows: 

struct group { 

char *gr_name; /* group name */ 

char *gr_passwd; /* group password */ 

gid_t gr_gid; /* group id */ 

char **gr_mem; /* group members */ 

}; 

RETURN VALUE 

Thegetgrentofunction returns the group information structure, or null ifthereareno moreentriesoran errar occurs. 
ERRORS 

enomem Insufficient memory to allocate group information structure. 
FILES 

/etc/group group database fi le 
CONFO RMSTO 

SVID 3, BSD 4.3 

SEEALSO 

fgetgrent(3), getgrnam(3), getgrgid(3) 

G N U , 4 Aprii 1993 



getgrnam, getgrgid 

getgrnam, getgrgid— G et group file entry 

SYNOPSIS 

#include <grp.h> 

#include <sys/types.h> 

struct group *getgrnam(const char *n a me | 

struct group *getgrgid (gid_t giti); 



DESCRIPTION 

The getgrnam o function returns a pointer to a structure contai ni ng thegroup information from /etc/group for the entry that 
matches the group name n a me . 

The getgrgido function returns a pointer to a structure contai ni ng thegroup information from /etc/group for the entry that 
matches the group id g d. 

Thegroup structure is defi ned in <grp.n> asfollows: 

struct group { 

char *gr_name; /* group name */ 
char *gr_passwd; /* group password */ 
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gid_t gr_gid; /* group id */ 

char **gr_raem; /* group members */ 

>; 

RETURN VALUE 

Thegetgrnamoand getgrgidf) functions return thegroup informati on structure, orNULL if the matching entry isnotfound 
or an error occurs. 

ERRORS 

enomem I nsuffi ci ent memory to allocate group information structure. 

FILES 

/etc/group group database fi le 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEEALSO 

fgetgrent(3), getgrent(3), setgrent(3), endgrent(3) 

G N U , 4 Aprii 1993 

getlogin, cuserid 

getiogin, cuserid— G et usemame 
SYNOPSIS 

(finclude <unistd.h> 

char * getlogin ( void ); 

#include <stdio.h> 

char * cuserid ( char *string ); 

DESCRIPTION 

getlogin returnsa poi nter to a stri ng contai ning the nameof the user logged in on the controll ing terminal of the process, or 
a nuli pointer if this information cannot be determi ned. The stri ng isstatically allocateci and might beoverwritten on 
subsequent Calisto thisfunction or to cuserid. 

cuserid returns a poi nter to astring contai ning a usemame associated with the ef fedi ve user ID of the process. If st ri ng is 
nota nuli pointer, it should bean array that can hold at least i__cuserid characters; the stri ng is returned in thisarray. 
Otherwise, a pointer to astring in a stati c area is returned. This stri ng isstatically allocateci and might beoverwritten on 
subsequent Calisto thisfunction orto getlogin. 

Themacro i__cuserid isan integer Constant that indicateshow longan array you might need to storea username. i__cuserid is 
declared in stdio.n. 

T hese functions let your program positi vely identify the user who isrunning (cuserid) or the user who logged in this sessi on 
(getlogin). (Thesecan differwhen setuid programsareinvolved.) The user cannot do anythingto fool these functions. 

For most purposes, it ismoreuseful to use the environment vari ableLOGNAME to find outwho the user is. This is more flexible 
preci sely because the user can set logname arbitrarily. 



ERRORS 

enomem I nsuffi ci ent memory to allocate passwd structure 



getmntent, setmntent, addmntent, endmntent, hasmntopt 




FILES 

The /etc/passwd password database fi le /etc/utmp (or /var/adm/utmp, or wherever your utmp fi le lives these days— theproper 
location depends on your ìibc version) 

C0NF0RMST0 

POSIX.l. System V hasacuserid function that usesthereal user ID rather than the ef recti ve user ID . Thecuserid function 
wasincluded in the 1988 version of POSIX, but was removed from the 1990 version. 

BUGS 

U nfortunately, it isoften rather easy to fool getiogin(). Sometimes it does notwork at ali, because some program messed up 
the utmp file. Often, it givesonly thefirst eight charactersof thelogin name. The user currently logged in on the control li ng 
tty of your program need not be the user who started it. 

Nobody knows preci selywhatcuserido does; so 

■ Avoid itin portableprograms 

■ Avoid italtogether 

■ Usegetpwuid (geteuido) instead, if that iswhat you meant. 

Simply, donotUS9cuserid(). 

SEEALSO 

geteuid(2), getuid(2) 

Linux 1.2.13, 3 September 1995 



getmntent, setmntent, addmntent, endmntent, hasmntopt 

getmntent, setmntent, addmntent, endmntent, hasmntopt— G et fi lesystem descriptor fi le entry 

SYNOPSIS 

#include <stdio.h> 
#include <mntent.h> 

FILE *setmntent(const char *filep, const char *type); 
struct mntent *getmntent (FILE *filep); 
int addmntent(FILE *filep, const struct mntent *mn t ) ; 
int endmntent(FILE *filep); 

char 'hasmntopt (const struct mntent *mnt , const char *o pt ) ; 

D ESC RIPTIO N 

Theseroutinesareused to access the fi lesystem descri ption file/etc/fstab and themounted filesystem description file /etc/ 
mstab. 

The setmntent o function opens the filesystem description filef i i ep and returns a file pointer that can beused by 
getmntent o. The argumenttype isthetypeof access required and can takethesamevaluesasthemode argument of fopen(3). 

Thegetmntento function readsthenext linefrom the filesystem description filef i i ep and returns a pointer to astructure 
contai ni ng the broken-out fi elds from a line in the file The pointer pointsto a stati c area of memory that isoverwritten by 

Subsequent Calisto getmntent(). 

The addmntent o function adds the mntent structuremnt to theend of theopen filefilep. 
The endmntent o function closes the fi lesystem description filef i i ep. 

The hasmntopt) ) function scansthemnt _opt s field of the mntent structuremnt fora substri ng that matchesopt. (See 
<mntent.n> for vai id mount options.) 



Part III: Library Functions 
Themntent structure is defined in <mntent.h> asfollows: 

struct mntent { 



char 


*mnt_fsname; 


/ 


1 name of mounted filesystem */ 


char 


*mnt_dir; 


/ * 


filesystem patti prefix */ 




char 


*mnt_type; 




mount type (see mntent. h) */ 




char 


*mnt_opts; 




mount options (see mntent. h) 


*/ 


int 


mnt_f req ; 




dump frequency in days */ 




int 


rant_passno; 




pass number on parallel fsck 


*/ 



}; 

RETURN VALUE 

Thegetmntento function returns a pointer to themntent structure or null on fai Iure. 
Theaddmntento function returns 0 on success and 1 on fai Iure. 
T he endmntent ( ) functi ons always returns 1 . 

Thehasmntopto function returns the addressof the substri ng if a match isfound, and null otherwise. 
FILES 

/etc/fstab filesystem description file 
/etc/mtab mounted filesystem description file 

C0NF0RMST0 

BSD 4.3 

SEEALSO 

fopen(3), f stab(5) 

27 junel993 



getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent 

getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent— G et network entry 

SYNTAX 

«include <netdb.h> 
struct netent 'getnetent () 
struct netent 'getnetbyname (n a me ) 
char *na me ; 

struct netent *getnetbyaddr(net , type) 
long net ; int t ype ; 
void setnetent(st ayopen ) 
int st ayopen ; 
void endnetent() 

DESCRIPTION 

The getnetent, getnetbyname, and getnetbyaddr subroutineseach return a pointer to an objectwith the following structure 
contai ni ng the broken-out fi eldsof a line in the network database, /etc/networks: 

struct netent { 

char *n_name; /* officiai name of net */ 

char **n_aliases; /* alias list */ 

int n_addrtype; /* net number type */ 

long n_net; /* net number */ 

>; 



getopt 



The menibers of this structure are 

n name The officiai name of the network. 

rwiiases A zero-terminated list of alternate namesfor the network. 

rwddrtype The type of the network number returned: af_inet. 

n^net The network number. Network numbers are returned in machine byte order. 

If the s t a y o p e n f lag on asetnetent subroutine ìsnull, the network database isopened. Otherwisethesetnetent hastheeffect 
of rewi ndi ng the network database. The endnetent may be cai led to dose the network database when processi ng is com pietà 

Thegetnetent subrouti ne si m ply readsthenext linewhereasgetnetbyname and getnetbyaddr search until a matchingname or 
net number isfound (or until eof isencountered). The type must beAF_iNET. Thegetnetent subroutine keeps a pointer in 
the database, allowing successive Calisto beused to search the enti re fi le. 

A cali to setnetent must be made before a wniie loop using getnetent to perform initialization, and an endnetent must be 

USed after the loop. Both getnetbyname and getnetbyaddr make Calisto setnetent and endnetent. 

FILES 

/etc/networks 

DIAGNOSTICS 

N ull pointer (0) returned on eof or errar. 

SEEALSO 

networks(5), RFC 1101 

HI STORY 

Thegetnetent!), getnetbyaddr) ), getnetbyname)), setnetent (), and endnetent!) functions appeared in 4.2BSD. 

BUGS 

T he data space used bythesefunctionsis stati c; if future use requires the data, itshould becopied before any subsequentcalls 
to these functions overwriteit. Only Internet network numbers are currently understood. Expecting network numbers to fit 
in no morethan 32 bitsisprobably naive. 



getopt 

getopt— Parses command-lineoptions 
SYNOPSIS 

(finclude <unistd.h> 

int getopt (in t a r g c , char * const a r g v [ ] , 

const char *opt stri n g ) ; 
extern char * o p t a r g ; 
extern int optind, opterr, optopt; 
ffinclude <getopt.h> 

int getopt_long(int a r g c , char * const a r g v [ ] , 
const char *opt stri n g , 

const struct option "longopts, int "longindex); 
int getopt_long_only(int argc, char * const argv[] , 



const char *opt stri n g , 

const struct option "longopts, int "longindex); 
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DESCRIVO N 

Thegetopto function parsesthecommand-linearguments. Itsargumentsat-gc and argv aretheargument count and array as 
passed to the maino function on program invocati on. An element of argv that starts with - (and isnot exactly - or --) isan 
option element. T he characters of this element (asidefrom the initial -)areoption characters. Ifgetopto iscalled repeatedly, 
it returns successi vely each of the option characters from each of the option elements. 

If getopto finds another option character, it returns that character, updating the external variable opt nd and a stati c vari abl e 
nextchar so that the next cali to getopto can resumé the scan with thefollowing option character or argv element. 

If thereareno more option characters, getopto returns eof. Then optino 1 isthe index in argv of the first a r g v element that is 
not an option. 

optst ri ng isastring contai ni ng the legi ti mate option characters. If such a character isfollowed by a colon, the option 
requiresan argument, so getopt pi acesa pointer to thefollowing text in thesameargv element, orthetext of thefollowing 
argv element, in optar g.Two colonsmean an option takesan optional arg; if thereis text in the current argv element, it is 
returned in opt arg; otherwise, opt arg is set to e. 

By default, getargso permutes the contents of a r gv asit scans, so that eventually ali thenon-optionsareattheend. Two 
other modesarealso implemented. If the first character of optstring is+ or the environment variable posixly_correct isset, 
option processi ngstopsassoon asa non-option argument isencountered. If thefirst character of optstring is -, each non- 
option argv element is handled asif it were the argument of an option with character code 1. (Thisisused by programsthat 
werewritten to expect opti ons and other argv elements in any order and that careabout the ordering of the two.) The special 
argument - forcesan end of option-scanning regardlessof the scanning mode. 

If getopto doesnot recognizean option character, it printsan error messageto stderr, stores the character in optopt, and 
returns?. T he cali ing program may prevent the error message by setti ng opterr to 0. 

The getopt_iong( (function works like getopto, exceptthat it also accepts long options, started out by two dashes. Long 
option names may beabbreviated if the abbreviati on isuniqueor isan exact match for some defi ned option. A long option 
may takea parameter, of theform — arg=param or --arg param. 

ongopts is a pointer to thefirst element of an array ofstruct option declared in <getopt.n>: 

as struct option { 
const char *namc ; 
int has^arg ; 
int *f I ag ; 
int vai ; 

>; 

T he meani ngs of the different fields are 

name T he name of the long option. 

has_arg no_argument (or 0) if the Opti On does not take an argument, required_argument (or 1) if the 

option requiresan argument, oroptionai_argument (or 2) if the option takesan optional 
argument. 

fiag Specifies how results are returned for a long option. If fi ag ìsnull, getopt_iongo returns vai. 

(For example, the cai li ng program might set vai to the equi valent short option character.) 

Otherwise, getopt_iongo returns 0, and f i ag poi nts to a variable that is set to va iftheoption 

isfound, but left unchanged iftheoption isnot found. 
vai Thevalueto return orto load into the variable pointed to byti ag. 

The last element of the array hasto befilled with zeroes. 

If i ongi ndex isnotNULL, it pointsto a variable that isset to the index of the long option relative to i ongopts . 

getopt_iong_oniyo is like getopt_iong ( ) , but - aswell as -- can indicate a long option. If an option that starts with - (not --) 
doesn't match a long option but does match a short option, it is parsed asa short option instead. 
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RETURN VALUE 

The getopt ofunction returnstheoption character if theoption wasfound successfully, : if therewasa missing parameter for 
oneof theoptions, ? for an unknown option character, or eof for the end of theoption list. 

getopt_iongo and getopt_iong_oniy( ) also return theoption character when a short option isrecognized. For a long option, 
they return vai if f i a g ìsnull, and 0 otherwise. Errar and eof returns are the sameas for getopt o, plus? for an ambiguous 
match oran extraneous parameter. 

EN VIRO N M EN T VARI ABLES 

posixly_correct If thisisset, option processing stopsassoon asa non-option argument isencountered. 

EXAMPLE 

Thefollowing example program, from thesourcecode i 1 1 ustrates the use of getopt_iong() with most of its features: 

#include <stdio.h> 
int 

main (a r g c , a r g v ) 
int ar gc ; 
char **argv ; 

{ 

int c ; 

int di gì t _ o p t i nd = 0; 

while (1) 

{ 

int this_option_optind = opti n d ? optind : 1; 

int opt i on i n d e x = 0; 

static struct option I ong opti ons[ ] = 

{ 

{"add", 1, 0, 0}, 
{"append", 0, 0, 0>, 
{"delete" , 1 , 0, 0}, 
{"verbose", 0, 0, 0}, 
{"create", 1, 0, 'e'}, 
{"file", 1, 0, 0g, fa, 0, 0, 0} 

>; 

c = getopt_long (arge, argv, "abc:d:012", 

I ong opt i ons, Sopt i o n _ i ndex ) ; 
if (c == -1) 

break; 
switchfc ) 
{ 

case 0: 

printf ("option %s", o n g_ opt i o n s [ o pt i on_ i nd ex ] . na me ) ; 

if ( o p t a r g ) 
printf (" with arg %s", optarg); 

printf ("\n"); 

break; 
case '0': 
case '1': 
case '2': 

if (digit_optind != 0 && di gi t_opti nd ! = thi soptionopti nd) 
printf ("digits occur in two different argv-elements . \n" ) ; 
di gi t_opti nd = thts_opti on_opti nd; 
printf ( "option %c\n" , c ) ; 
break; 
case 'a': 
printf ( "option a\n" ) ; 
break; 
case 'b': 
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printf ("option b\n"); 
break; 
case 'c': 

printf ("option c with value '%s'\n", optarg); 
break; 
case 'd': 

printf ("option d with value '%s' \n", optarg); 

break; 
case '?': 

break; 
default: 

printf ("?? getopt returned character code 0%o ??\n", c); 

> 

} 

if (opt i n d < argc ) 
{ 

printf ("non-option ARGV-elements : "); 
while (opt i n d < argc ) 

printf ( "%s " , ar gv[ opt i nd++] ) ; 
printf ("\n"); 

} 

exit (0); 
} 

BUGS 

Thisman pageisconfusing. 
CONFO RMSTO 

getopto: PO SIX.l, provided theenvironment variableposixLY_coRRECT isset. Otherwise, theelementsof argv aren't 

really const, becausethey get permuted. They'reset const in the prototype to be compati ble with other 
systems. 

G N U , 30 August 1995 

getpass 

getpass— G ets a password 
SYNOPSIS 

#include <pwd.h> 

#include <unistd.h> 

char *getpass( const char * prompt ); 

DESCRIPTION 

The getpass function displays a prompt to, and readsin, a password from, /dev/tty. If thisfileis not accessi ble, getpass 
displays the prompt on the standard errar output and readsfrom the standard input. 

The password may beupto_PAsswoRD_i_EN (currently 128) characters in length. Any additional charactersandtheterminat- 
ing newl ine character arediscarded. (Thismight bedifferent in Linux.) 

getpass turns off character echoing while reading the password. 

RETURN VALUES 

getpass return s a pointer to thenull-terminated password. 



getprotoent, getprotobyname, getprotobynumber, setprotoent, endprotoent 

FILES 

/dev/tty 

SEEALSO 

crypt(3) 

HI STORY 

A getpass function appeared in Version 7 AT&T UN IX. 
BUGS 

The getpass function leaves its result in an internai stati c object and returns a pointer to that object. Subsequent Calisto 
getpass will modify thesameobject. 

Thecalling processshould zero the password assoon as possi bleto avoid leavingthecleartext password visiblein the 
process's address space. 

BSD M an Page29 N ovember 1993 



getprotoent, getprotobyname, getprotobynumber, setprotoent, 
endprotoent 

getprotoent, getprotobyname, getprotobynumber, setprotoent, endprotoent— G et protocol entry 

SYNOPSIS 

#include <netdb.h> 

struct protoent *getprotoent(void) ; 

struct protoent *getprotobyname(const char *name); 

struct protoent *getprotobynumber(int proto); 

void setprotoent(int stayopen); 

void endprotoent(void) ; 

D ESC RIFTIO N 

The getprotoento function readsthenext linefrom the file /etc/protocois and returns a structure protoent contai ning the 
broken-out fieldsfrom theline The/etc/protocois fileisopened if necessary. 

The getprotobyname! ) function returns a pr ot oe nt structure for the li ne from /etc/protocois that matches the protocol name 

name. 

Thegetprotobynumbero function returns a pr ot oe nt structurefor the linethat matches the protocol numbernumber. 
The setprotoent o function opensand rewindsthe /etc/protocois file. If stayopen istrue (1), thefilewill not beclosed 

between Calisto getprotobyname) ) Or getprotobynumber(). 
The endprotoent!) function Closes /etc/protocols. 

The protoent structure isdefined in <netdb.h> asfollows: 

struct protoent { 

char *p_name; /* officiai protocol name */ 

char **p_aliases; /* alias list */ 

int p_proto; /* protocol number */ 

} 
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T he members of the protoent structure are 

p name The officiai nameof the protocol. 

p aiiases A zero-terminated list of alternative names for the protocol. 

pjroto The protocol number. 

RETURN VALUE 

Thegetprotoento, getprotobyname) ), and getprotobynumbero functions return the protoent structure, oraNun pointer if an 
error occurs or the end of the fi le is reached. 

FILES 

/etc/protocois protocol database file 
C0NF0RMST0 

BSD 4.3 

SEEALSO 

getservent(3), getnetent(3), protocols(5) 

BSD, 24 Aprii 1993 

getpw 

getpw— Reconstructs password line entry 
SYNOPSIS 

#include <pwd.h> 

«include <sys/types.h> 

int getpw(uid_t uid, char *buf); 

D ESC RIPTIO N 

Thegetpwo function reconstructs the password li ne entry for the given user UID uid in the buffer b u f . Thereturned buffer 
contains a lineof format 

name : passwd : uid :gid:gecos: dir: shell 

Thepasswd structure is defined in <pwd.h> asfollows: 

struct passwd { 



char 


*pw__name; 


/* 


jsername*/ 


char 


*pw_passwd; 


/* 


user password */ 


uid_t 


pw_uid; 


/* 


user id */ 


gid_t 


pw_gid; 


/* 


group id */ 


char 


*pw_gecos; 


/ * 


real name */ 


char 


*pw_dir; 




home directory */ 


char 


*pw_shell; 


/* 


shell program */ 



>; 

RETURN VALUE 

Thegetpwofunction returnsa on success, or -1 if an error occurs. 



ERRORS 

enomem I nsuffi ci ent memory to allocate passwd structure. 



getpwent, setpwent, endpwent 

FILES 

/etc/passwd Password databasefile 
SEEALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), putpwent(3), passwd(5) 

GNU, 27 May 1996 

getpwent, setpwent, endpwent 

getpwent, setpwent, endpwent— get password file entry 

SYNOPSIS 

#include <pwd.h> 

#include <sys/types.h> 

struct passwd *getpwent(void) ; 

void setpwent(void) ; 

void endpwent (void) ; 

D ESC RIPTIO N 

The getpwento function returns a pointer to a structure contai ni ng the broken-out fieldsof a line from /etc/passwd. The 
firsttimeit iscalled it returns the first entry; thereafter, it returns successive entries. 

The setpwento function rewinds the fi le pointer to thebeginning of the /etc/passwd file 

Theendpwent)) function ClOSesthe /etc/passwd file. 

The passwd structure isdefi ned in <pwd.n> asfollows: 

struct passwd { 



char 


*pw_name; 


/*! 


jsername*/ 




char 


*pw_passwd; 


/* 


user password 


*/ 


uid_t 


pw_uid; 


/* 


user id */ 




gid_t 


pw_gid; 


/* 


group id */ 




char 


*pw_gecos; 


/* 


real name */ 




char 


*pw_dir; 


/* 


home directory 


*/ 


char 


*pw_shell; 


/* 


shell program 


*/ 



}; 

RETURN VALUE 

The getpwent ofunction returns the passwd structure, or null if there are no more entries or an error occurs. 
ERRORS 

enomem Insufficient memory to allocate passwd structure. 

FILES 

/etc/passwd Password databasefile 
C0NF0RMST0 

SVID 3, BSD 4.3 

SEEALSO 

fgetpwent(3), getpwnam(3), getpwuid(3), getpw(3), putpwent(3), passwd(5). 

GNU, 27 May 1996 
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getpwnam, getpwuid 

getpwnam, getpwuid— Get password fi le entry 
SYNOPSIS 

#include <pwd.h> 
«include <sys/types.h> 

struct passwd *getpwnam(const char * name); 
struct passwd *getpwuid(uid_t uid); 

D ESC RIPTIO N 

The getpwnam o function returns a pointer to astructurecontainingthebroken outfieldsof alinefrom /etc/passwd forthe 
entry that matchestheusernamename. 

The getpwuid o function returns a pointer to a structure contai ni ng the broken-out fieldsof a linefrom /etc/passwd forthe 
entry that matches the user U I D uid. 

Thepasswd structure is defined in <pwd.n> asfollows: 

struct passwd { 



char 


*pw_name; 


/"username*/ 


char 


*pw_passwd; 


/* user password */ 


uid_t 


pw_uid; 


/* user id */ 


gid_t 


pw_gid; 


/* group id */ 


char 


*pw_gecos; 


/* real name */ 


char 


*pw_dir; 


/* home directory */ 


char 


*pw_shell; 


/* shell program */ 



}; 

RETURN VALUE 

The getpwnam o and getpwuid o functions return thepasswd structure orNULL if the matching entry isnot found or an errar 
occurs. 



ERRORS 

ENOMEM 



Insufficient memory to allocate passwd structure 



FILES 

/etc/passwd Password databasefile 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEEALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwent(3), passwd(5) 



GNU, 27 May 1996 



f getc, f gets, getc, getchar, gets, ungete 

fgetc, fgets, getc, getchar, gets, ungete— Input of characters and Strings 

SYNOPSIS 

«include <stdio.h> 

int fgetc(FILE *st r eam) ; 

char *fgets(char *s,int size, FILE *stream); 



getservent, getservbyname, getservbyport, setservent, endservent 

int getc(FILE *st ream) ; 
int getchar(void) ; 
char *gets(char *s ) ; 
int ungetc(int c, FILE *stream); 

DESCRIPTION 

tgetco readsthenext character from st ream and returnsit asan unsigned char cast to an int, or eof on end of file or error. 
getco isequivalent to tgetco except that it can beimplemented asa macro that evaluatesst ream morethan once. 

getchar() ÌS equivalent tO getcfstd n). 

getsoreadsa line from stdin into the buffer pointed to by s until either a termi nati ng newlineor EOF, which it replaces 
with \o. N o check for buffer overrun isperformed (seethefollowing"Bus" section). 

fgetso readsin at most onelessthan n characters from st ream and storesthem into the buffer pointed to by s. Reading stops 
after an eof or a newline. If a newlineisread, it isstored into the buffer. \e isstored after the last character in the buffer. 

ungetco pushesc back to st r eam, cast to unsigned char, whereit isavailablefor subsequent read operations. Pushed-back 
characters wi II bereturned in reverse order; only onepushback isguaranteed. 

Calisto thefunctionsdescribed nere can bemixed with each otherand with Calisto other input functions from thestdio 
library for the same i nput stream . 

RETURN VALUES 

tgetco, getco, and getcharo return thecharacter read asan unsigned char cast to an int, or eof on end of file or error. 
getso and fgetso return s on success, and null on error orwhen end of fileoccurswhileno characters havebeen read. 
ungetco returnsc on success, or eof on error. 

CONFO RMSTO 

ANSI-C, POSIX.l 

BUGS 

Becauseit is impossi bleto teli without knowing the data in advancehow many characters getso will read, and because 
getso will continue to store characters past the end of the buffer, it isextremely dangerousto use. It hasbeen used to break 
computer security. Use fgetso instead. 

It is not advisableto mix Calisto input functions from thestdio library with low-level Calisto reado for the file descriptor 
associ ated with the input stream; the results will beundefined and very probably notwhatyou want. 

SEEALSO 

read(2), write(2), fopen(3), fread(3), scanf(3), puts(3), fseek(3), ferror(3) 

GNU, 4 Aprii 1993 

getservent, getservbyname, getservbyport, setservent, 
endservent 

getservent, getservbyname, getservbyport, setservent, endservent— G et Service entry 

SYNOPSIS 

#include <netdb.h> 

struct servent *getservent(void) ; 

struct servent *getservbyname(const char *name, const char *proto); 
struct servent *getservbyport(int port, const char *p r o t o ) ; 
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void setservent(int stayopen); 
void endservent (void) ; 

DESCRIVO N 

Thegetserventofunction reads the next linefrom thefile/etc/services and returns a structure, servent, contai ni ng the 
broken out fieldsfrom the line The /etc/services file isopened if necessary. 

Thegetservbyname()function returnsa servent structurefor the linefrom /etc/services that matches the servi cenarne usi ng 

protocol proto. 

Thegetservbyportofunction return sa ser vent structure for the li ne that matches the port port given in network byteorder 
usi ng protocol proto. 

Thesetserventofunction opens and rewinds the /etc/services file. If stayopen istrue {1), thefilewill not beclosed between 

Cai I S tO getservbyname ( ) and getservbyport ( ) . 
The endservent () function Closes /etc/services. 

Theser vent structure is defi ned in <netdb.h> asfollows: 

struct servent { 

char *s _ n a me ; /* officiai service name */ 

char **s_aliases; /* alias list */ 

int s port ; /* port number */ 

char *s proto; /* protocol to use */ 

} 

T h e m em bers of th e s e r v e n t structu re are: 

s_name The officiai name of the service. 

s _ a i i ases A zero-terminated list of alternative names for the servi ce. 

s port The port number for the service, given in network byteorder. 

s. proto T he name of the protocol to usewith th i s servi ce. 

RETURN VALUE 

Thegetservento, getservbyname(), and getservbyport ( ) functions return thes e r v e n t structure, or a null pointer if an error 
occursortheend of thefileisreached. 

FILES 

/etc/services Servi ces database fi le 
C0NF0RMST0 

BSD 4.3 

SEEALSO 

getprotoent(3), getnetent(3), services(5) 

BSD, 22 Aprii 1996 

getusershell, setusershell, endusershell 

getusershell, setusershell, endusershell— Get legai user Shells 

SYNOPSIS 

#include <unistd.h> 
char *getusershell(void) ; 



getutent, getutid, getutli ne, pututli ne, setutent, endutent, utmpname 

void setusershell(void) ; 
void endusershell(void) ; 

D ESC RIPTIO N 

Thegetusersheiio function returnsthe next linefrom the fi le / etc/sheiis, openingthefileif necessary. The line should 
contain thepathnameof a valid user shell. If /etc/sheiis does not exist or isunreadable, getusersheiio behavesas if /bin/sh 
and /bin/csh werelisted in the file. 

Thesetusershell() function rewinds /etc/shells. 

TheendusershellO function Closes /etc/shells. 

RETURN VALUE 

Thegetusersheiio function returnsaNULL pointer on end of file 
FILES 

/etc/shells 

C0NF0RMST0 

BSD 4.3 

SEEALSO 

shells(5) 

BSD , 4 July 1993 

getutent, getutid, getutline, pututline, setutent, endutent, 
utmpname 

getutent, getutid, getutline, pututline, setutent, endutent, utmpname— Access utmp fi le entri es 

SYNOPSIS 

#include <utmp.h> 

struct utmp *getutent(void) ; 

struct utmp *getutid(struct utmp *ut); 

struct utmp *getutline(struct utmp *ut); 

void pututline(struct utmp *ut); 

void setutent(void) ; 

void endutent(void) ; 

void utmpname(const char Mi le); 

DESCRIPTION 

utmpnameo sets the name of the utmp-format filefor the other utmp functions to access. If utmpnameo isnotused to set the 
filenamebeforetheotherfunctionsareused, they assume pathjjtmp, asdefined in <paths.h>. 

setutent o rewinds the file pointer to thebeginning of the utmp file. It isgenerally agood ideato cali it beforeany of the 
other functions. 

endutent o closes the utmp file. It should becalled when the user code isdone accessi ng the fi le with the other functions. 

getutent o reads a linefrom thecurrent file position in the utmp fi le. It returns a pointer to a structure contai ni ng the fields 
of the line. 

getutidosearchesforward from thecurrent file position in theutmp filebased on ut . If ut ->ut_type ìsrun_lvl, boot_time, 
new_time, or old_time, getutid o will find thefirst entry whoseut type field matchesut ->ut_type. If ut ->ut_type is 
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init_process, login_process, user_process, or dead_process, getutido will find the fi rst entry whose ut^id field matches 
ut ->ut_id. 

getutiineo searchesforward from the current file position in theutmp file. It scansentries whose ut typeisusER_PR0CEss or 
login_process and returns the fi rst one whose ut iine field matches ut ->ut_iine. 

pututnneowrites theutmp structureut into theutmp fi le. It usesgetutido to search fortheproper place in the file to insert 
thenew entry. If it cannot find an appropriate slot for ut , pututiinen will append thenew entry to the end of the fi le. 

RETURN VALUE 

getutento, getutido, and getutiineo return a pointer to astruct utmp, which isdefined in <utmp.h>. 
FILES 

/var/run/utmp— Database ofcurrently logged-in users 
/var/iog/wtmp— D atabaseof past user logins 

C0NF0RMST0 

XPG 2, SVID 2, Linux FSSTN D 1.2 

SEEALSO 

utmp(5) 

Linux libc 5.0.0, 22 M ardi 1995 

getw, putw 

getw, putw— Input and output of words (ints) 
SYNOPSIS 

#include <stdio.h> 

int getw(FILE *s t r e a m ) ; 

int putw(int » ,FILE*s t r e a m) ; 

DESCRIPTION 

getw readsa word (that is, an int) from st r eam. It'sprovided for compati bility with SVID . I recommend you usetread(3) 
instead. putw writes the word w (that is, an int) to st ream. It isprovided for com pati bility with SVID, but I recommend you 
usetwrite(3) instead. 

RETURN VALUES 

N ormally, getw returnstheword read, and putw returnstheword written. On errar, they return eof. 
BUGS 

Thevaluereturned on errar isalso a legitimate data value. terror(3) can beused to disti ngui sh between thetwo cases. 
C0NF0RMST0 

SVID 

SEEALSO 

f read(3), fwrite(3), ferror(3), getc(3), putc(3) 

GNU, 16 September 1995 



glob, globfree 



glob, globf ree 

giob, globfree— Find pathnames matching a pattern; f ree memory fra m globo 
SYNOPSIS 

#include <glob.h> 

int glob(const char 'pattern, ìnt flags, 
int e r r f u ne (const char * epath, int eerrno), 
globjt *pgl ob ) ; 
void globfree (glob t * p g I o b ) ; 

DESCRIVO N 

Thegiobo function searches forali the pathnames matching pattern accordingto therulesused bytheshell (seegiob(7)). 
N o tilde expansion orparametersubstitution isdone 

Thegiobfreeo function frees the dynamically allocateci Storage from an earlier cali to globo. 

Theresultsof agiobo cali arestored in the structure pointed to by pgiob, which is a giob_t that isdeclared in <giob.b> as 

typedef struct 
{ 

int glpathc; /* Count of patbs matched so far */ 

char **gl_pathv; /* List of matched pathnames. */ 
int gl_offs; /* Slots to reserve in ' gl pathv 1 . */ 

int gl_flags; /* Flags for globbing */ 

} glob_t; 

Results arestored in dynamically allocateci Storage. 

Theparameter 1 1 a g s ismadeup of bitwiseOR of zero or more the following symbolic constants, which modify theof 
behavior of globo: 

glob_err Return on read errar (because a directory does not have read permission, forexample). 

glob_mark Append aslash to each path which correspondsto a directory. 

glob_nosort D on't sort the returned pathnames (they are by default). 

glob_doofs p g i o b ->g i _ o f t s slotswill be reserved at thebeginning of the list of strings in pgi ob ->patbv. 

glob_nocheck If no pattern matches, return the originai pattern. 

glob_append Append to theresultsof a previous cali. D o not set thisflag on the first invocation of giob(). 

globjoescape M età characters cannot be quoted by backslashes. 

glob_period A leading period can be matched by meta characters. 

If errfunc isnot null, itwill be called in caseof an errar with the arguments epath, a pointer to the path that failed, and 
eerrno, the value of ermo as returned from oneof the Calisto opendiro, readdiro, or stato. If errfunc returns nonzero, or 
if glob_err isset, globo wi 1 1 termi nate after the cali to errfunc. 

U pon successful return, pgi ob ->gi _pat he contai ns the number of matched pathnames and pgi ob ->gi _ p a t hv a pointer to the 
list of matched pathnames. T he fi rst pointer after the last pathname is null. 

It is possi bleto cali globo several times. In that case, the glob_append flag hasto beset in f i ags on thesecond and later 
invocations. 

RETURN VALUES 

On successful completion, globo returns 0. Other possiblereturnsare 
glob_nospace For running out of memory, 

glob_abend For a read error, and 

glob nomatch For no found matches. 
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EXAMPLES 

Oneexampleof use isthefollowing code, which simulates typing in the shell: 
ls -1 *.c ../*.c 

glob_t globbuf; 
globbuf .gl_offs = 2; 

globC*. o", GLOB_DOOFS, NULL, &globbuf); 

glob("../*.c", GLOB__DOOFS | GLOB_APPEND, NULL, &globbuf); 

globbuf .gl_pathv[0] = "ls"; 

globbuf .gl_pathv[1 ] = "-1"; 

execvp( "ls" , &globbuf .gl__pathv[0] ) ; 

CONFORMSTO 

ProposedPOSIX.2 

BUGS 

Thegiobofunction mayfail dueto failureof underlyingfunction cai I s, such asmaiioco or opendiro. Thesewill storetheir 
error code in ermo. 

P0SIX.2 isnot yet an approved standard; theinformation in thisman page is subject to change. 
SEEALSO 

ls(l), sh(l), exec(2), stat(2), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7) 

GNU, 13 May 1996 



hosts_access, hosts_ctl 

hosts_access, hosts_cti— Access-control li brary functions 
SYNOPSIS 

#include "log_tcp.h" 

extern int allo w_ severi t y ; 

extern int deny sever i t y ; 

int hosts_access(daemon ; client) 

char *d a e mo n ; 

struct client_info *client; 

int hosts_ctl(daemon, ci i e n t _ n a me , ci i ent_addr, ci i ent_user ) 
char *d a e mo n ; 
char *cl i e n t _ ri a me ; 
char *cl i ent_addr ; 
char *cl i e n t _ u s e r ; 



DESCRIPTION 

Theroutinesdescribed in thisdocument are part of the ìibwrap. a library. They implement a pattern-based access-control 
languagewith optional shell commandsthat areexecuted when a pattern fires. 

In ali cases, thedaemon argument should specify a daemon processname (arguì o] value). The client host addressshould bea 
valid address, or fromjjnknown if the addresslookup fai led. The client hostnameand username should beempty stringsif no 
information isavailable, from_unknown if the lookup fai led, oran actual hostname or username. 

hosts_access(> consults the access-control tablesdescribed in thehosts_access(5) manual page. hosts_access() returnso if 
access should bedenied. 

hosts_cti ( ) is a wrapper around the hosts_access ( ) routi ne with a perhaps more convenient i nterface (although i t does not 
passon enough information to support automated remote username lookups). hosts_ctio returnse if access should be 
denied. 



hcreate, hdestroy, hsearch 

The ai i ow_s everi ty and deny_severi ty vari ables determine how accepted and rejected requestscan belogged. They must be 
provided by the Caller and can bemodified by rulesin the access-control tabi es. 

DIAGNOSTICS 

Problemsarereported viathesysiog daemon. 

SEEALSO 

hosts_access(5) (format of the access control tables), hosts_options(5), optional extensionsto the base language 
FILES 

/etc/hosts. access, /etc/hosts.deny access-control tables 

BUGS 

Thefunctionsdescribed heredo not makecopiesof their string-valued arguments. Bewareof datafrom functionsthat 
overwritetheirresultson each cali. 

hosts^accesso uses the strtok( ) library function. T his may i nterfere with other codethat relieson strtoko. 
AUTHOR 

W ietse Venema (wietse@wzv.win. tue. ni) 

D epartment of M athematics and C omputing Science 
Eindhoven U niversity of Technology 

Den Dolech 2, P.O. Box513, 5600 M B Eindhoven, TheN etherlands 

hcreate, hdestroy, hsearch 

hcreate, hdestroy, hsearch— H ash table management 
SYNOPSIS 

#include <search.h> 

ENTRY *hsearch(ENTRY item, ACTION action); 
int hcreatefunsigned nel ); 
void hdestroy(voi d ) ; 

D ESC RIPTIO N 

Thesethreefunctionsallow the user to create a hash table that associatesa key with any data. 

First, the table must becreated with the function hcreate) ). nei isan estimate of the num ber of entri es in the table. 
hcreate o may adjust thisvalue upward to improve the performance of the resulti ng hash table. TheGN U implementation 
of hsearch o will also enlarge thetable if it getsnearly full. maiioc(3) isused to allocate space for the table. 

T he corresponding function hdestroy o frees the memory occupi ed by the hash table so that a new table can beconstructed. 

item isoftype entry, which isatypedef defined in <search.h> and includestheseelements: 

typedef struct entry 
{ 

char *key ; 
char *dat a ; 
} ENTRY; 

key pointsto the zero-termi nated ASC 1 1 stri ng that isthesearch key. data pointsto the data associ ated with that key. (A 
pointerto atypeother than character should becastto pointer-to-character.) hsearch osearches the hash table for an item 
with thesamekey asi tem, and if successful returns a pointer to it. a e ti on determi neswhat hsearch o does after an unsuccess- 
ful search. A valueof enter instruets itto insertthenew item, whereasa valueof find meansto return null. 




Part III: Library Functions 



RETURN VALUE 

hcreateo returnsNULL if the hash tablecannot besuccessfully installed. 

hsearchoreturnsNULL if act i on ìsenter and there isinsufficient memory to expand thehash table, or if act i on ìsfind and 
temcannot befound in thehash table 

C0NF0RMST0 

SVID, except that in SysV, thehash tablecannot grow. 

BUGS 

Theimplementation can manageonly onehash table at a ti me. Individuai hash table entri escan beadded, but not deleted. 
EXAMPLE 

Thefollowing program i nserts 24 itemsinto a hash table and then printssomeof them: 

#include <stdio.h> 
#include <search.h> 

char *data|]={ "alpha", "bravo", "charley", "delta", 
"echo", "fox-trot", "golf", "hotel", "india", "juliette", 
"kilo", "lima", "mike", "november", "oscar", "papa", 
"quebec", "romeo", "Sierra", "tango", "uniform", 
"Victor", "whiskey", "x-ray", "yankee", "zulù" 

>; 

int main() 
{ 

ENTRY e, *ep ; 
int i ; 

/* start with small table, and let it grow */ 
hcreate(3) ; 

for (i = 0; i < 24; i ++) 
{ 

e. k e y = datali]; 

/* data is just an integer, instead of a pointer 

to something */ 
e . data = (char *)i ; 
ep = hsearchfe , ENTER) ; 
/* there should be no failures */ 

if (ep == NULL) {f printf (stderr, "entry failed\n" ) ; exit(1);} 

} 

for (i = 22 ; i < 26; i ++) 

/* print two entries from the table, and show that 
two are not in the table */ 

{ 

e k e y = datali]; 

ep = hsearch(e , FIND) ; 

printf ("%9.9s -> %9.9s:%d\n" , e.key, e p ?e p - >k e y : "NULL" , 
e p ? (int ) (ep ->dat a ) :0) ; 

> 

return 0; 



SEEALSO 

bsearch(3), lsearch(3), tsearch(3), malloc(3) 



GNU, 30 September 1995 



inet_aton, inet_addr, inet_network, i net_ ntoa, inet_makeaddr, i net_ Inaof, i net_netof 




hypot 

hypot— Euclidean distance function 
SYNOPSIS 

#include <math.h> 

doublé hypot (doublé x, doublé y); 

DESCRIVO N 

The hypot o function returnsthesqrt(x*x+y*y). T his isthe length of the hypotenuse of a right-angle triangle with sidesof 
length x andy, or the distance of the poi nt (x, y) from the ori gin. 

CONFO RMSTO 

SVID 3, BSD 4.3 

SEEALSO 

sqrt(3) 

25 Junel993 

index, rindex 

index, rindex— Locate character in stri ng 
SYNOPSIS 

#include <string.h> 

char *index(const char *s,int c); 

char *rindex(const char *s,int c); 

DESCRIPTION 

The index ( ) function returns a pointer to the first occurrence of the character c in the string s . 
Therindexo function returns a poi nterto the last occurrence of the character c in the string s . 
The termi nati ngNun character isconsidered to bea part of the strings. 

RETURN VALUE 

The indexo and rindex o functions return a pointer to thematched character, orNULL if the character isnot found. 
C0NF0RMST0 

BSD 4.3 

SEEALSO 

memchr(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 

GNU, 12 Aprii 1993 

inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, 
inet_lnaof, inet_netof 

inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, inet_netof— Intemet addreSS-manipulation 

routines 
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SYNOPSIS 

«include <sys/socket.h> 
«include <netinet/in.h> 
#include <arpa/inet.h> 

int inet_aton(const char *cp, struct in_addr *inp); 
unsigned long int inet_addr(const char *cp); 
unsigned long int inet_network(const char *cp); 
char *inet_ntoa(struct in_addr in); 
struct in_addr inet_makeaddr(int net, int host); 
unsigned long int inet_lnaof (struct in_addr in); 
unsigned long int inet_netof (struct in_addr in); 



DESCRIVO N 

inet_atono converts the I nternet hostaddresscp from the standard numbers-and-dotsnotation into bi nary data and stores it 
in thestructurethatinp pointsto. inet_aton returns nonzero if theaddress isvalid, and a if itisnot. 

Theinet_addr()function converts the I nternet hostaddresscp from numbers-and-dotsnotation into bi nary data in network 
byteorder. If theinput isinvalid, -1 isreturned. Thisisan obsolete interface to inet_aton; it is obsolete because -1 isavalid 
address (255.255.255.255), and inet_aton providesacleanerwayto indicate errar return. 

Theinet_network() function extracts the network number in network byteorder from theaddresscp in numbers-and-dots 
notation. If theinput isinvalid, -1 isreturned. 

Theinet_ntoa() function converts the Internet host address given in network byte order to a stri ng i n standard numbers- 
and-dots notation. The stri ng isreturned in astatically allocateci buffer, which subsequent callswill overwrite. 

Theinetjnakeaddro function makesan Internet host addressin network byteorder by combining the network number net 
with the locai address host in network net , both in locai host byteorder. 

Theinet_inaof o function returnsthe locai host address part of the Internet address n . T he locai host address isreturned in 
locai host byte order. 

The inet_netot( (function returns the network number part of the Internet address i n. The network number isreturned in 
locai host byteorder. 

Thestructurein_addr asused in inet_ntoa(), inet_makeaddr(), inet_lnoaf ( ) , and inet_netof () isdefined in netinet/in.h as 

struct in_addr { 
unsigned long int saddr; 
} 

N otethat on the Ì80x86 the host byteorder is Least Significant Byte first, whereas the network byteorder, asused on the 
Internet, is M ost Significant Byte first. 

CONFO RMSTO 

BSD 4.3 

SEEALSO 

gethostbyname(3), getnetent(3), hosts(5), networks(5) 

BSD,3Septemberl995 



infnan 

intnan— Dealswith i nfinite or not-a-number (N aN ) result 
SYNOPSIS 

«include <math.h> 
doublé infnan(int error); 



initgroups 95 

D ESC RIPTIO N 

Theinfnano function returns a suitable value for infinity and not-a-number (N aN ) results. Thevalueof error can beERANGE 
to represent infinity, or anything elseto represent N aN . ermo isalso set. 

RETURN VALUE 

If error is erange (Infinity), huge_val is return ed. 

If error ÌS -ERANGE (-1 nfinity), -HUGE_VAL ÌS retumed. 

If error is anything else, NaN is retumed. 
ERRORS 

erange Thevalueof error is positiveor negative infinity. 

edom Thevalueof error is not-a-number (N aN ). 

C0NF0RMST0 

BSD 4.3 

GNU, 2 junel993 

initgroups 

initgroups— Initializes the supplementary group access list 
SYNOPSIS 

#include <grp.h> 
«include <sys/types.h> 

int initgroupsfconst char "user , gid_t group); 

D ESC RIPTIO N 

The initgroupso function initializes the group access list by reading the group database /etc/group and usi ng ali groupsof 
which user isa member. The additi onal group group isalso added to the list. 

RETURN VALUE 

The initgroups) ) function returnsa on success, or -1 if an error occurs. 
ERRORS 

eperm The calling processdoesnot havesufficient privileges. 

enomem I nsuffi ci ent memory to allocate group information structure. 

FILES 

/etc/group group database fi le 
C0NF0RMST0 

SVID 3, BSD 4.3 

SEEALSO 

getgroups(2), setgroups(2) 

GNU, 5 Aprii 1993 
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inndcomm 

inndcomm— IN N D communication part of InterN etN ews library 
SYNOPSIS 

#include "inndcomm.h" 
int ICCopen() 
int ICCclose() 
void ICCsettimeout(i) 
int i ; 

int ICCcommand(c md, a r g v , replyp) 

char cmd; 

char *a r g v| ] ; 

char **r e p I y p ; 

int ICCcancel(mesgi d ) 

char *me s g i d ; 

int ICCreserve(why ) 

char *why; 

int ICCpause(why ) 

char *why ; 

int ICCgo(why ) 

char *why ; 

extern char *l CCf ai Iure; 



DESCRIVO N 

Theroutinesdescribed in thismanual page are part of the InterN etN ews library, iibinn(3). They areused to send com- 
mandsto a running innd(8) daemon on the locai host. T he lettersl CC stand for Innd Control Command. 

iccopen createsa U N IX-domain datagram socket and bindsit to the server's control socket. It returns-1 on fai Iure or 0 on 
success. T hi s routine must becalled beforeany other routine. 

iccciose closesany descriptorsthat havebeen created by iccopen. 1 1 returns -1 on fai Iure or 0 on success. 

iccsettimeout can be callecl beforeany of the following routinesto determine how long the library should wait beforegiving 
up on getti ng the server's reply. Thisisdoneby settingand catchingasiGALRM signai(2). If the timeout islessthan 0, no 
reply will bewaited for. Thesc_SHUTDowN, sc_xabort, and sc_xexec commandsdo not get a reply either. The default, which 
can beobtained by setti ng the timeout to 0, isto wait until the server replies. 

icccommand sends the command c md with parametersargv to theserver. It returns-1 on errar. If the server replies, and rep yp 
isnot null, it will be fi lied in with an allocateci buffer that contai ns the full text of the server's reply. T hi s buffer is a stri ng in 
theform <di gi t s ><s pace ><t e x t > wheredi gì ts is the text valueof therecommended exit code; 0 indicates success. Replies 
longer than 4,000 byteswill betruncated. The possi blevaluesof cmd aredefined in theinndcomm.h header file. The param- 
etersfor each command aredescribed in ctiinnd(8). T hi s routine returns -1 on communication fai Iure; on success it returns 
th e exi t statu s sen t by t h e server, whichwillneverben egati ve. 

icccancei sendsacancel messageto theserver. me s g i d isthemessagelD of the article that should becanceled. The return 
value i s the same as for icccommand. 

iccpause, iccreserve, and iccgo send a pause, reserve or go command to theserver, respectively. If iccreserve isused, the 
why value used in theiccpause invocation must match; the value used in theiccgo invocation must always match theone 
used in theiccpause invocation. The return value for ali three routinesis the same as for icccommand. 

If anyof theseroutinesfail, theicctaiiure variablewill identify the system cali thatfailed. 
HIST0RY 

Written by Rich $alz (rsaizuuunet.uu.net) for InterN etN ews. 



SEEALS0 

ctlinnd(8), innd(8), libinn(3). 



isalnum, isalpha, i sasci i , isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, i supper, i sxdi gi t 

insque, remque 

insque, remque — I nsert/ R sn ove an item from aquaie 
SYNOPSIS 

#include <stdlib.h> 

void insque(struct qelem * eleni, struct qelem * prev); 
void remquefstruct q e I e m*e I em) ; 

D ESC RIPTIO N 

insque o and remque o arefunctionsfor mani pulati ng queuesmadefrom doubly linked lists. Each element in thislist isof 

type struct qelem. 

Theqeiem structure isdefined as 

struct qelem { 
struct qelem *q_forw; 
struct qelem *q_back; 
char q_data[1 ] ; 
}; 

insque o inserts the element pointed to by e i e m immediately after the element pointed to by prev, which must not beNULL. 
remque o removes the element pointed to by e i emfrom the doubly linked list. 

CONFO RMSTO 

SVR4 

BUGS 

Theq_data field issometimesdefined to beof type char *, and under Solaris 2.x, it doesn't appear to exist at ali. 

The location of theprototypesforthesefunctionsdiffersamongseveral versionsof U N IX. Somesystemsplacethem in 
<search.n>, othersin <string.n>. Linux places them in <stdiib.h> becausethat seemsto makethemostsense 

Some versionsof U N IX (such asH P-UX lO.x) do not define a struct qelem but rather nave the argumentsto insque o and 

remque () beof type void *. 

GNU, 30 October 1996 

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, 
islower, isprint, ispunct, isspace, isupper, isxdigit 

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit — 

Character classification routines 
SYNOPSIS 

#include <ctype.h> 

int isalnum (int c ) ; 

int isalpha (int c ) ; 

int isascii (int c ) ; 

int isblank (int c ) ; 

int iscntrl (int c ) ; 

int isdigit (int c ) ; 

int isgraph (int c ) ; 

int islower (int c ) ; 

int isprint (int c ) ; 

int ispunct (int c ) ; 
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int isspace (int c ) ; 
int isupper (int c ) ; 
int isxdigit (int c ) ; 

D ESC RIPTIO N 

T hese functions check whether c, whi eh must havethevalueof an unsigned cnar or eof, fallsinto a certain character class 
accordi ngto thecurrent locale: 

isainumo C hecksfor an alphanumeric character; it is equi valent to (isaipha(c) \ \ isdigit(c)). 

isaiphao C hecksfor an alphabetic character; in the standard C locale, it isequivalentto (isupper(c) | 

isiower(c)). In some locales, there may be additional charactersforwhich isaiphao istrue— 

letters that are neither uppercase nor lowercase. 
isasciio Checks whether c is a 7-bit unsigned charvalue that fitsinto the ASC II character set. T hi s 

function isa BSD extension and isalso an SVID extension. 
isbianko C hecksfor a blank character; thatis, a space or a tab.This function isaGNU extension. 

iscntno C hecksfor a control character. 

isdigito C hecks for a digit (0 through 9). 

isgrapno Checksforany printable character except space, 

isioweri ) Checks for a lowercase character. 

isprinto Checksforany printable character, including space. 

ispunct ( ) C hecksfor any printable character that is not a space or an alphanumeric character. 

isspace o C hecksfor whitespace characters. They arespace, form-feed ('\f ■), na/vline('\n'), carriage 

return ('\r'), horizontal tab('\t'), and vertical tab('\v). 
isupper o Checks for an uppercase letter. 

isxdigit o Checksforahexadecimaldigit(thatis,oneof0 1 2 34 5 6 7 8 9 0 abcdefABC D E F). 

RETURN VALUE 

Thevaluesreturned are nonzero if the character c fai Is into thetested class, and 0 if it doesnot. 
C0NF0RMST0 

AN SI C, BSD 4.3. isasciio isa BSD extension and isalso an SVID extension. isbianko isa G N U extension. 
BUGS 

Thedetailsof what characters belong in whi eh class depend on thecurrent locale. For example, isupper 0 will not recognize 
an A with an umlaut (À) asan uppercase letter in the default C locale. 

SEEALSO 

tolower(3), toupper(3), setlocale(3), ascii(7), locale(7) 

GNU,2Septemberl995 

isatty 

isatty— Tests whether thisdescriptor refersto a terminal 
SYNOPSIS 

#include <unistd.h> 
int isatty (int d e s c ) ; 

DESCRIPTION 

isatty returnsi if desc is an open descriptor connected to a terminal, and 0 otherwise. 



jO, jl, jn, yO, yl, yn 



959 



CONFORMSTO 

SVID,AT&T,X/OPEN,BSD 4.3 

SEEALSO 

fstat(2), ttyname(3) 

Linux, 20 Aprii 1995 



isinf, isnan, finite 

isinf, isnan, finite— Test for infinity or not-a-number (N aN ) 
SYNOPSIS 

#include <math.h> 
int isinf (doublé vai ue ) ; 
int isnan(double vai ue ) ; 
int f inite(double vaine); 

DESCRIPTION 

T he isinf o function returns-1 if vaiue represents negative infinity, 1 if vaiue represents positi ve infinity, and 0 otherwise. 

The isnan 0 function returns a nonzero vaiue if vai ue is not-a-number (N aN ), and 0 otherwise. 

The finiteo function returns a nonzero vaiue if vai ue isfiniteor isnot a not-a-number (N aN) vaiue, and 0 otherwise. 

CONFORMSTO 

BSD 4.3 

GNU,2Junel993 



j0, j1, jn, y0,y1,yn 

j0, ji, jn, yo, yi, yn— Bessel functions 
SYNOPSIS 

#include <math.h> 

doublé j0(double x ) ; 

doublé j1 (doublé x ) ; 

doublé jnfint n, doublé x); 

doublé y0(double x ) ; 

doublé y1 (doublé x ) ; 

doublé ynfint n, doublé x); 

DESCRIPTION 

The jB() and jio functions return Bessel functionsof xof the first kind of ordersO and 1, respectively. The jnofunction 
returns the Bessel function of xof the first kind of order n. 

They0() and yi() functions return Bessel functionsof x of thesecond kind, ordersO and 1, respectively. Theynofunction 
returns the Bessel function of x of thesecond kind, ordern. 

Forthefunctionsy0(), yi 0 and yn 0, the vaiue of x must be positive. For negati ve values of x, these functions return 

-HUGE_VAL. 

CONFORMSTO 

SVID 3, BSD 4.3 
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BUGS 

There are erro rsof up to 2e-16 in thevalues returned by jao, ji (), and jn() for valuesof x between -8 and 8. 

26 Junel993 

killpg 

kiiipg— Sends a signal to ali membersof a processgroup 
SYNOPSIS 

#include <signal.h> 

int killpg ( pid_t pidgrp, int signal ) ; 

DESCRIPTION 

The kiiipg o function causes the signal signal to besentto ali theprocessesin the processgroup pi dgrp orto the processes' 
own processgroup if pidgrp isequal to 0. 

It ÌS equivalent tO kill( -pidgrp, signal) ;. 

RETURN VALUE 

T he value returned is-1 on errar, or a for success. 

ERRORS 

Errors are returned in ermo and can beoneof the followi ng: 

einval Signal is invalid. 

esrch Processgroup does not exi st. 

eperm TheuserID of the calling process isnot equal to that of the process the signal issent to, and theuser ID is 

not that of the super-user. 

SEEALSO 

kill(2), signal(2), signal(7) 

GNU, 4 Aprii 1993 

labs 

ìabs— C omputes the absolute value of a long integer 
SYNOPSIS 

#include <stdlib.h> 

long int labs(long int j ) ; 

DESCRIPTION 

Theiabso function computes the absolute value of the long integer argumentj . 

RETURN VALUE 

Returns the absolute value of the long integer argument. 

CONFO RMSTO 

SVID 3, BSD 4.3, ISO 9899 




NOTES 

T rying to take the absolute value of the most negative i nteger is not defi ned. 
SEEALSO 

abs(3), ceil(3), f loor(3), fabs(3), rint(3) 

GNU, 6 Junel993 

ldexp 

ìdexp— M ultipliesfloating-point number by integrai power of 2 
SYNOPSIS 

#include <math.h> 
doublé ldexp(double x, int exp); 

DESCRIPTION 

The ìdexp o function returnstheresult of multi plying the floating-point number x 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

f rexp(3), modf(3) 

ldiv 

idiv— Computes the quoti ent and remainder of long integer division 
SYNOPSIS 

#include <stdlib.h> 

ldiv_t ldiv (long int n u me r , long int denom); 

DESCRIPTION 

T he idiv o function computes the value numer /denom and returnsthequotient and remainder in a structure named idiv_t 
that containstwo long integer members named quot and rem. 

RETURN VALUE 

Theidiv_t structure 

CONFO RMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

div(3) 

GNU, 29 March 1993 



by 2 raisedto the power exp. 



BSD, 6 Junel993 
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lgamma 

ìgamma— Logs gamma function 
SYNOPSIS 

#include <math.h> 
doublé lgamma(double x); 

D ESC RIPTIO N 

Theigammao function returnsthe log of theabsolutevalueof theGammafunction. Thesign of the Gamma function is 
returned in theexternal integer si gngam. 

For negative integer valuesof x, ìgammao returnsHUGE_vAL, and ermo is set to erange. 
ERRO RS 

erange Invalid argument— negative integer valueofx. 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEEALSO 

infnan(3) 

BSD, 25 Junel993 

libinn 

ìibinn— InterN etN ews library routines 
SYNOPSIS 

(finclude "libinn. h" 
typedef struct _TIMEINFO { 

timej t i me ; 

long u 5 e c ; 

long t z o n e ; 
> TIMEINFO; 

char *GenerateMessageID() 

void HeaderCleanFrom(f r o m) 
char *f r o m ; 

char *HeaderFind(Ar t i ci e, H e a d e r , size) 
char 'Artide; 
char "Header ; 
int size; 

FILE *CAopen ( F r o mS e r v e r , ToServer) 
FILE *F r o mS e r v e r ; 
FILE *T o S e r ver ; 

FILE *CAlistopen(F r omSer ver , ToServer, request) 
FILE *F r o mS e r v e r ; 
FILE 'ToServer ; 
char "request ; 



void CAclose() 

struct _DDHANDLE *DDstart (F r o mS e r i e r , T o S e r v e r ) 
FILE *F r o mS e r v e r ; 
FILE *T o S e r ver ; 
> DDHANDLE; 

void DDcheck(h, group ) 
DDHANDLE *h ; 
char *group ; 

char * DDend(h ) 
DDHANDLE *h ; 

void CloseOnExec(f d, flag) 
int f d ; 
int f I ag ; 

int SetNonBlocking(f d, flag) 
int f d ; 
int flag; 

int LockFile(f d, flag) 
int f d ; 
int flag; 

char * GetConf igValue(vai uè ) 
char *13 1 ne ; 

char * GetFileConfigValue(val ne ) 
char "vaine; 

char * GetFQDN() 

char * GetModeratorAddress(group ) 
char *group ; 

int GetResourceUsage(us er 1 1 me, sys 1 1 me ) 
doublé *y s er t i me ; 
doublé *syst I me ; 

int GetTimeInfo(now ) 
TIMEINFO *now; 

int NNTPlocalopen(FromServerp, ToServerp, errbnff) 
FILE **F r o mS e r ver p ; 
FILE "ToSer ver p ; 
char *er r buf f ; 

int NNTPremoteopen(F r omSer ver p, ToServerp, errbuff) 
FILE **F r o mS e r ver p ; 
FILE "ToSer ver p ; 
char *er r buf f ; 

int NNTPconnect(host , FromServerp, ToServerp, errbuff) 

char *host ; 

FILE **F r omSer ver p ; 

FILE "ToSer ver p ; 

char *er r buf f ; 

int NNTPcheckarticle(t ext ) 
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char *t ext ; 

int NNTPsendarticle(t ext , T o S e r v e r , Terminate) 
char *t ext ; 
FILE *T o S e r ver ; 
int Ter mi n a t e ; 

int NNTPsendpassword(ser ver , FromServer, ToServer) 
char *server ; 
FILE 'FromServer ; 
FILE *T o S e r ver ; 

void Radix32(val y e , p ) 
unsigned long vai ne ; 
char *p ; 

char * ReadInFile(name, Sbp) 
char *name ; 
struct stat *Sbp ; 

char * ReadInDescriptor(f d, Sbp) 
int f d ; 

struct stat *Sbp ; 



char * INNVersion() 

D ESC RIPTIO N 

ìibinn is a library of utility routine for manipulating U senet arti ci es and related data. It isnot necessary to usetheheader file 
ìibinn.n; if it isnot available, it isonly necessary to properly declarethenMEiNFO datatype, asshown in the precedi ng code 

GenerateMessageiD usesthecurrent ti me processID, and fui ly qualified domain nameof the locai host to create a M essage 
ID header that ishighly likely to beunique. Thereturned valuepointsto stati c space that isreused on subsequent cai I s. 

HeadercieanFrom removes the extraneous i nformation from thevalueof aFrom or Repiy-To header and leaves just the offici al 
mailing address. In particular, thefollowing transformati ons are madeto thefrom parameter: 

address -> add r es s 
address (s t u f f ) -> address 
st nf f <addr ess >-> address 

Thetransformationsaresimpleand arebased on RFC 1036, which li mits the format of the header. 

HeaderFind searches through Arti ci e lookingforthespecified Header . si ze should bethelength of the header name It 
returns a pointer to thevalueof the header, skipping leading whitespace, or null if the header cannot befound. Art i ci e 
should bea standard C stri ng contai ni ng the text of the article; the end of a header isindicated by ablank line: two 
consecutive \n characters. 

CAopen and CAciose provi de news eli ents with access to theactivefile; thecA standsfor Client Acti ve. cAopen opensthe 
active(5) filefor reading. It returns a pointer to an open file, or null on errar. If a locai or an N FS-mounted copy exists, 
CAopen will use that file.TheFromServer and ToServer parameters should beFiLESConnected to theN NTP server for input 
and output, respectively. (Seethediscussionsof NNTPremoteopen and NNTPiocaiopen later in thissection.) If either parameter is 
null, CAopen will just return null if the fi le isnot locally available. If neither is null, CAopen will usethem to query theN NTP 
server usi ng the "list" command to makealocal temporary copy. 

ThecAiistopen sends a "list" command to the server and returns a temporary file contai ni ng the results. Ther eqnest 
parameter, if not null, will besent asan argument to thecommand. U nlikecAopen, thisroutinewill never usea locally 
available copy of theactivefile. 

CAciose closestheactivefileand removes any temporary filethat might havebeen created bycAopen orcAiistopen. 



libinn 




cioseonExec can make a descri ptor close-on-exec so that it isnot shared with any child processe. If theflag is nonzero, the fi le 
isso marked; if it is 0, the close-on-exec modeiscleared. 

DDstart, DDcheck, and DDend areused to settheDistribution header; theDD standsfor D efault D i stributi on. The 
dist rib . pats(5) fi le is consulted to determi ne the proper value for the Distribution header after al I newsgroups have been 
checked. DDstart beginstheparsing. It returns a pointer to an opaquehandlethatshould beused on subsequentcalls. The 
FromServer and ToSer ver parameters should beFiLESConnected to theN NTP server for input and output, respectively. If 
either parameter ìsnull, an empty default wi II ulti mately bereturned if the fi le isnot locally available. 

DDcheck should be called with thehandle, h, returned by DDstart and a new group, g r □ u p , to check. It can becalled asoften as 
necessary. 

DDend releases any state mai ntai ned in thehandle and returns an allocated copy of the text that should beused for the 
Distribution header. 

setNonBiocking enables (if f 1 ag isnonzero) or disablesfif f 1 ag is e) non-blocking I/O on theindicated descri ptor. It returns 
-1 on fai Iure and 0 on success. 

LockFiie triesto lock the fi le descri ptor fd. If f i ag isnonzero it will block until thelock can bemade; otherwiseit will return 
-1 if the file cannot belocked. It returns -1 on fai Iure and 0 on success. 

Getconfigvaiue returns the value of the specified configuration parameter. (Seeinn.conf(5) for detailson the parameters and 
their interpretation.) The returned value poi ntsto stati c space that isreused on subsequent calls. 

GetFiieconfigvaiue returns the specified configuration parameter from theinn.conf fi le without checking for any defaults. 
The returned value poi ntsto stati c space that isreused on subsequent calls, orNULL if the value isnot present. 

GetFQDN returns the fui ly qualified domain nameof the locai host. The returned value poi ntsto static space that isreused on 
subsequent calls, or null on errar. 

GetModeratorAddress returns the mailing addressof the moderator for the specified group or null on errar. (Seemoderators(5) 
for detailson how theaddress isdetermined.) GetModeratorAddress doesno checking to seeif the specified group isactually 
moderated. The returned value poi ntsto static space that isreused on subsequent calls. 

GetResourceusage fi lls in the u s e r t i me and systi me parameters with the total user and system timeused by thecurrent process 
and any children it may havespawned. It getsthevalues by doingatimes(2) system cali. It returns -1 on fai Iure, or oon 
success. 

GetTimeinto fi lls in the n o w parameter with information about thecurrent timeandtzone. Theti me andusec fieldswill be 
fi lied in by a cali to gettimeofday(2).Theti me field will befilled in by a cali to time(2), and theusec field will beset to 0.The 
t zone field will be fi lied in with thecurrent offset from GMT. T hi sisdoneby calli ng iocaiame(3) and taking the value of 
thetmjmtof f field, negati ng it, and dividi ng it by 60. Thisisdoneby callingiocaitime(3) and com pari ng the value with that 
returned by a cali to gmtime(3). For efficiency, thet zone fi dd isonly recalculated if morethan an hour haspassed sincethe 
lasttimeGetTimeinfo was called. T his routi ne returns -1 on failure, and 0 on success. 

NNTPiocaiopen opens a connection to the private port of an InterN etN ews server runningon the locai host. It returns -1 on 
failure, or 0 on success. Fromserverp andToServerp will befilled inwith FiLESthat can beused to com munì cate with the 
server, e r r b □ f f can either beNULL or a pointer to a buffer at least 512 bytes long. If it isnot null, and the server refusesthe 
connection, it will befilled in with the text of theserver's reply. This routine isnot for general use; it is a subroutine for 
compati bility with systems that have U N IX-domain stream sockets. It always returns -1. 

NNTPremoteopen does the sameas NNTPiocaiopen, except that it calls Getconfigvaiue to find the name of the locai server and 
opens a connection to the standard N NTP port. Any client program can use this routi ne. It returns -1 on failure, oro on 
success. 

NNTPconnect is the same as NNTPremoteopen, except that the desi red host isgiven asthehost parameter. 

NNTPcheckarticie veri fi es that the text meets theN NTP limitationson I i ne length. It returns -1 on failure, or 0 if the text is 
valid. 



Part III: Library Functions 



NNTPsendarticie writestext on ToServer using N NTP conventions for linetermination. Thetext should consist of oneor 
morelinesendingwith a newline. If Termi nate isnonzero, theroutinewill also writetheN NTP data-termination marker on 
thestream. It returns-1 on fai Iure, or 0 on success. 

NNTPsendpassword sends authenti cation information to an N NTP server by fi nding the appropriate entry in the 

passwd.nntp(5) file server Contai ns the name Of the hOSt; GetConfigValue will beused if server ÌSNULL. FromServer and 

ToServer should be files that are connected to the server. N 0 action istaken if the specified host isnot listed in the password 
file. 

Radix32 convertsthenumber in vai ne into aradix-32 string in the buffer pointed to by p. Thenumber is split into fi ve-bit 
pieces, and each piece is con verted into a character using the alphabet 0... 9a... vto represent the numbers 0-32. Only the 
lowest 32 bitsof vai ue areused, so p need only pointto a buffer of eight bytes(seven charactersand the trai ling 

ReadinFiie readsthefile named name into allocateci memory, appendi ng a termi nati ng \o byte. It returns a pointer to the 
space, or null on errar. If sbp isnot null, it istaken astheaddressof a placete storetheresultsof a stat(2) cali. 

ReadinDescriptor performs the same function asReadinFiie, exceptthatfd refersto an already-open file. 

iNNVersion return s a pointer to a string identifying the IN N version, suitablefor printing in logon banners. 

EXAMPLES 

char *p ; 

char *Ar t i ci e ; 

char b u f f [ 2 5 6 ] ; 

FILE *F ; 

FILE "ToSer ver ; 

FILE *FromServer ; 

if ((p = Header-Find (Artide, "From", 4)) == NULL) 

Fatali "Can't find From line"); 
(void)strcpy(buf f , p); 
HeaderCleanFrom(buf f ) ; 

if ((F = CAopen(Fr omSer ver , ToServer)) == NULL) 

Fatali "Can't open active file"); 
/* Don't pass the file on to our children. */ 
CloseOnExecff ileno(F ) , 1); 
/* Make a locai copy. */ 

p = ReadInDescriptor(f ileno(F ) , (struct stat *)NULL); 
/* Close the file. */ 
CAclose( ) ; 

if (NNTPremoteopen(&FromServer , &ToServer) < 0) 

Fatali "Can't connect to server"); 
if ((p = GetModeratorAddressf "comp.sources.unix" ) ) == NULL) 
Fatali "Can't find moderator 's address"); 

HI STORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEE ALSO 

active(5), dbz(3z), parsedate(3), inn.conf(5), inndcomm(3), moderators(5), passwd . nntp(5) 

GN U, 30 October 1996 

libpbm 

ìibpbm— Functions to support portable bitmap programs 
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SYNOPSIS 

#include <pbm.h> 
ce . . . libpbm. a 

D ESC RIPTION-PACKAG EWIDE ROUTINES 

T he followi ng secti ons descri be stri ng and fi le management routi nes avai lable i n libpbm. 

KEYWORD MATCH IN G 

T he followi ng does a case- i n sensi ti ve match of s t r against k e y wo r d : 

int pm_keymatch( char* str, char* keyword, int mi n c h a r s ) 

su can bea leading substri ngof keyword, but at least mi ne ha rs must bepresent. 
LOG BASE TWO 

Thisconverts between amaxvai and theminimum number of bitsrequired to hold it: 

int pm_maxvaltobits(int ma x v a ) 
int pm_bitstomaxval(int bits) 

M ESSAG ESANO ERRO RS 

This is a printf o-style routineto writean informational message 

void pm_message (char* f mt , ... ) 

This is a printf o style routineto writean errar message and abort: 

void pm_error(char* f mt , ... ) 

The followi ngwrites a usage message; the stri ngshould indicatewhat arguments areto beprovided to the program: 

void pm_usage(char* usage) 

GENERIC FILE MANAGEMENT 

Thefollowing opensthegiven filefor reading, with appropriate errar checking: 

FILE* pm_openr (char* nane) 

A filenameof - istaken asequivalentto stdin. 

Thefollowing opensthegiven filefor writing, with appropriate errar checking: 

FILE* pm_openw(char* nane) 

The followi ngcloses the fi le descri ptor, with appropriate errar checking: 

void pm_close(FILE* f p ) 

ENDIAN I/O 

Thefollowing are routi nes to read and write short and long intsin either big- or little-endian byteorder: 

int pm_readbigshort(FILE* in, short* sP) 

int pm_writebigshort(FILE* out , short s) 

int pm_readbiglong(FILE* in, long* IP) 

int pm_writebiglong(FILE* out, long I ) 

int pm_readlittleshort(FILE* in, short* sP) 

int pm_writelittleshort(FILE* out , short s ) 

int pm_readlittlelong(FILE* in, long* IP) 

int pm_writelittlelong(FILE* out , long I ) 

D ESC RIPTIO N - PBM-SPEC IFIC ROUTINES 

T he followi ng secti ons descri be fi le management routi nes avai lable i n libpbm. 
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TYPESAND CONSTANTS 

Each bit should contai n only thevaluesof pbm_white or pbm_black: 

typedef ... bit; 
#def ine PBM_WHITE . . . 
#def ine PBM_BLACK . . . 

These are routines for distinguishing different fileformats and types: 

#def ine PBM_FORMAT . . . 
#def ine RPBM_FORMAT . . . 
#define PBM_TYPE PBM_FORMAT 
#define PBH_FORMAT TYPE(f ) ... 

INITIALIZATION 

Ali PBM programs must cali this routine: 

void pbm_init(int* argcP, char* argv[] ) 

MEMORY MANAGEMENT 

This allocates an array of bits: 

bit** pbm_allocarray(int cols, int rows) 

This allocates a row of the given number of bits: 

bit* pbm_allocrow(int cols) 

This frees the array allocateci with pbm_aiiocarrayo containing the given number of rows: 

void pbm_f reearray(bit** bits, int rows) 

This frees a row of bits: 

void pbm_f reerow(bit* bit row) 

READ IN G FILES 

This reads the header from a PBM file filling in the rows, coi s, and format variables: 

void pbm_readpbminit(FILE* fp, int* colsP, int* rowsP, int* formatP) 

This reads a row of bitsinto the b i trow array (for ma t and coi s are fi lied in by pbm_readpbminito): 

void pbm_readpbmrow(FILE* fp, bit* bitrow, int cols, int format) 

This function COmbineSpbm_readpbminit(), pbm_allocarray(), and pbm_readpbmrow( ) : 
bit** pbm_readpbm(FILE* fp, int* colsP, int* rowsP) 

It reads an entirebitmapfileinto memory, returning the allocateci array and filling in the rows and coi s variables. 
This reads an enti re fi le or input stream of unknown sizeto a buffer and allocates more memory asneeded: 

cbar* pm^read unknown size(FILE* fp, long* nread) 

The cali ing routine hasto freetheallocated buffer with treeo. pm_read_unknown_size() returns a pointer to the allocateci 
buffer: the nread argument returns the number of bytesread. 

WRITING FILES 

T his writes the header for a portable bitmap fi le: 

void pbm_writepbminit(FILE* f p , int cols, int rows, int f or c e p I a I n ) 

Thef orcepi ai n flag forces a piai n-format fi le to bewritten, asopposed to a raw-formatone 
Thiswri tesa row from a portable bitmap: 

void pbm_writepbmrow(FILE* f p , bit* bitrow, int cols, int f or c ep I a I n ) 
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Thiswritestheheaderand ali data for a portable bitmap: 

void pbm_writepbm(FILE* f p , bit** b i t s , int c o I s , int r o ws , int forcepl ai n ) 
Thisfunction combine pbm_writepbminit() and pbmj»ritepbmrow(). 

SEEALSO 

libpgm(3), libppm(3), libpnm(3) 

AUTHOR 

Copyright e 1989, 1991 byTony Hansen andjef Poskanzer 

libpgm 

libpgm— Functionsto support portable graymap programs 
SYNOPSIS 

#include <pgm.h> 

ce . . . libpgm. a libpbm.a 

DESCRIPTION 

Thefollowing sectionsdescribememory and file management routines available in libpgm. 

TYPESAND CONSTANTS 

Eachgray should contain only thevalues between 0 and pgmjiaxmaxval. 

pgm_pbmmaxvai is the max vai used when a PGM program readsa PBM file. N ormally it isi, but for some programs, a larger 
value gives better results. 

typedef ... gray; 

#def ine PGM_MAXMAXVAL . . . 

extern gray pgm_pbmmaxval; 

Thefollowing are for disti nguishingdifferent fileformats and types: 

#def ine PGM_FORMAT . . . 
#def ine RPGMFORMAT . . . 
#define PGM_TYPE PGM FORMAT 
int PGM_FORMAT_TYPE (int format) 

INITIALIZATION 

Ali PGM programs must cali thisroutine: 

void pgm_init(int* argcP, char* a r g v [ ] ) 

MEMORY MANAGEMENT 

T his allocates an array of grays: 

gray** pgm_allocarray(int cols, int rows) 

Thisallocatesa row of thegiven number of grays: 

gray* pgm_allocrow(int cols) 

T his frees the array allocateci with pgm_aiiocarrayo containing thegiven number of rows: 

void pgm_f reearray(gray** grays, int rows) 

T his frees a row of grays: 

void pgm_f reerowfgray* grayrow) 
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READ IN G FILES 

Thisreadstheheader from a PG M fi le, fi II i ng in the r o ws , coi s , ma x v a i , and f o r ma t vari ables: 

void pgm_readpgminit(FILE* fp, int* colsP, int* rowsP, gray* ma x v a I P , 
int* f o r ma t P ) 

Thisreadsarow of graysinto thegrayrow array. f ormat , coi s, and max vai are fi lied in by pgm_readpgminito: 

void pgm_readpgmrow(FILE* fp, gray* grayrow, int cols, gray maxval, int format) 

T his function COmbineSpgm_readpgminit(), pgm_allocarray( ), and pgm_readpgmrow( ) : 
gray** pgm_readpgm(FILE* fp, int* colsP, int* rowsP, gray* maxvalP) 

It readsan entiregraymapfileinto memory, returni ng the al located array and filling in therows, coi s, and max vai variables. 

WRITING FILES 

Thiswrites the header for a portablegraymap file 

void pgm_writepgminit ( FILE* fp, int cols, int rows, gray maxval , 
int forceplain ) 

Thef orcepi ai n flag forces a plain-format fileto bewritten, asopposed to a raw-formatone 
Thiswrites a row from a portable graymap: 

void pgm_writepgmrow(FILE* fp, gray* grayrow, int cols, gray maxval , 
int forceplain) 

T his function combinespgm_writepgminito and pgm_writepgmrowo; it writes the header and ali data for a portablegraymap: 

void pgm_writepgm( FILE* f p , gray** gr ays , int cols, int r ows , gray maxval , int forceplain) 

SEEALSO 

lippbm(3), libppm(3), libpnm(3) 

AUTHOR 

Copyright e 1989, 1991 byTony Hansen andjef Poskanzer. 

libpnm 

ìibpnm— Functionsto support portable anymap programs 
SYNOPSIS 

#include <pnm.h> 

ce . . . libpnm. a libppm.a libpgm.a libpbm.a 

D ESC RIPTIO N 

Thefollowing sections describe memory and file management routines available in libpnm. 
TYPESAND CONSTANTS 

Each xei contai nsthreexeivais each of which should contain only a valuebetween a and pnm maxmaxval. pnmjbmmaxvai is 
the maxvai used when a PN M program readsa PBM file. N ormally it isi, but for some programs, a larger valuegives better 
results. 

typedef ... xel; 

typedef ... xelval; 

#def ine PNM_MAX MAXVAL . . . 

extern xelval pnmpbmmaxval; 
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XEL MAN IPU LATIO N S 

Thismacro extractsasinglevaluefrom an xei when you know it'sfrom a PBM or PGM file: 

xelval PNM_GET1 ( xel x ) 

When the xei isfrom a PPM file useppM_GETR(), ppm_getgo, and ppm getbo. 
Thismacro assigns a si ngle value to an xei when you know it'sfrom a PBM or PGM file: 

void PNM_ASSIGN1( xel x, xelval v ) 

When the xei isfrom a PPM file, useppM_AssiGN(). 
This macro checks two xeisfor equali ty: 

int PNM_EQUAL( xel x, xel y ) 

Thisoneisfordistinguishing different fi le types: 

int PNM_FORMAT TYPE( int format ) 

INITIALIZATION 

Ali PNM programs must cali this routine: 

void pnm_init( int* argcP, char* argv[] ) 

MEMORY MANAGEMENT 

Thisallocates an array of xeis: 

xel** pnm_allocarray( int cols, int rows ) 

This allocates a row of thegiven number of xeis 

xel* pnm_allocrow( int cols ) 

Thisfrees the array allocateci with pnm_aiiocarrayo that contai ns thegiven number of rows: 

void pnm_f reearray( xel** xels, int rows ) 

Thisfreesa row of xeis: 

void pnm_freerow( xel* xelrow ) 

READ IN G FILES 

Thisreadstheheader from a PN M file, fi Ili ng in the rows, cols, maxvai, and format variables: 

void pnm_readpnminit( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 

Thisreadsarow of xdsinto thexeirow array. format, cols, and maxvai arefilled in by pnm_readpnminito: 

void pnm_readpnmrow( FILE* fp, xel* xelrow, int cols, xelval maxvai, int format ) 

Thisreads an entireanymap fileinto memory, returning the allocateci array and filling in the rows, cois, maxvai, and format 
variables: 

xel** pnm_readpnm( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 

Thisfunction combinespnm_readpnminito, pnm_aiiocarray( ), and pnm_readpnmrow( ) . U nli ke the equi valent functions in 
PBM , PGM , and PPM , it returns the format so you can teli whattype the file is. 

WRITING FILES 

Thiswri tes the header for a portableanymap file: 

void pnm_writepnminit ( FILE* fp, int cols, int rows, xelval maxvai, int format, 
int force-plain) 
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U nlike the equi valent functions in PBM , PGM , and PPM , you haveto specify the output type The forceplain flagforcesa 
piai n-format f i le to bewritten, asopposed to a raw-formatone. 

Thiswritesa row from a portable anymap: 

void pnm_writepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, 
int forceplain ) 

This writes the header and ali data for a portable anymap: 

void pnm_writepnm( FILE* fp, xel** xels, int cols, int rows, xelval maxval, int format, 
int forceplain ) 

This function COmbineSpnm_writepnminit() and pnm_writepnmrow(). 

FORMAT PROMOTION 

Thispromotesa row of xelsfrom onemaxvai and formatto a new set: 

void pnm_promotef ormatrow( xel* xelrow, int cols, xelval maxval, int format, xelval new-maxval, 
int newformat ) 

U se this when combining multi pie anymaps of different types— just take the maxi mum value of themaxvais and the max of 
theformats, and promote them ali to that. 

Thispromotesan enti re anymap: 

void pnm_promotef ormat ( xel** xels, int cols, int rows, xelval maxval, 
int format, xelval newmaxval, int newformat ) 

XEL MAN IPU LATIO N 

These return awhiteor black xei, respectively, for the given maxvai and format: 

xel pnm_whitexel( xelval maxval, int format ) 
xel pnm_blackxel( xelval maxval, int format ) 

Thisinvertsan xei: 

void pnm_invertxel( xel* x, xelval maxval, int format ) 

Thisfiguresout an appropriate background xei based on this row: 

xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format ) 

Thisfiguresout a background xei based on an entire anymap: 

xel pnmJ)ackgroundxel( xel** xels, int cols, int rows, xelval maxval, 
int format ) 

Thiscan do aslightly better job than pnm_backgroundxeirow(). 
SEEALSO 

pbm(3), pgm(3), ppm(3) 

AUTHOR 

Copyright ® 1989, 1991 byTony Hansen and Jef Poskanzer. 
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libppm 

libppm— Functionsto support portable pixmap programs 
SYNOPSIS 

#ìnclude <ppm.h> 

ce . . . libppm. a libpgm.a libpbm.a 

TYPESAND CONSTANTS 

typedef ... pixel; 
typedef ... pixval; 
#def ine PPM_MAXMAXVAL . . . 
extern pixval ppm_pbmmaxval; 

Each pixel contai nsthreepixvais, each of which should contai n only thevalues between 0 and ppm_maxmaxval. ppm_pbmmaxvai 
isthemaxvai used when a ppm program readsaPBM file N ormally it isl; however, for some programs, a larger valuegives 
better results. 

For disti nguishing different file formats and types, use 

#def ine PPM_FORMAT . . . 
#def ine RPPM_FORMAT . . . 
#define PPM_TYPE PPM_FORMAT 
int PPM_FORMAT_TYPE ( int format ) 

Thesethreemacrosretrievethered, green, or bluevaluefrom thegiven pixel: 

pixval PPM_GETR( pixel p ) 
pixval PPM_GETG( pixel p ) 
pixval PPM_GETB( pixel p ) 

Thismacro assi gns thegiven red, green, and bluevaluesto the pixel : 

void PPM_ASSIGN( pixel p, pixval red, pixval grn, pixval blu ) 

Thismacro checkstwo pixels for equality: 

int PPM_EQUAL( pixel p, pixel q ) 

T he following macro scales the colors of pixel p accordi ng the old and new maximum valuesand assi gns the new valuesto 
newp. It isintended to makewriting ppm to whatever easier. 

void PPM_DEPTH( pixel newp, pixel p, pixval oldmaxval, pixval newmaxval ) 

Thismacro determinestheluminanceof the pixel p: 
float PPM_LUMIN( pixel p ) 

MEMORY MANAGEMENT 

Allocate an array of pixels: 

pixel** ppm_allocarray( int cols, int rows ) 

Allocate a row of the gi ven number of pixels: 

pixel* ppm_allocrow( int cols ) 

Freethearray allocateci with ppm_aiiocarrayo containing thegiven number of rows: 

void ppm_f reearray( pixel** pixels, int rows ) 

Freea row of pixels: 

void pbm_f reerowf pixel* pixelrow ) 
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READING PBM FILES 

void ppm_readppminit( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP, ìnt* formatP ) 

Read theheaderfrom a ppm file, fi Ili ng in the rows, cois, maxvai, and format variables. 

void ppm_readppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxvai, int format ) 

Read a row of pixels into the pixelrow array. Format, cois, and maxvai werefilled in by ppm readppminito. 

pixel** ppm_readppm( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP ) 

Read an entirepixmap fi le into memory, returning the allocateci array and fi I li ng in the rows, cois, and maxvai variables. This 

function COmbineSppm readppminitO, ppm_allocarray( ), and ppm_readppmrow( ) . 

WRITING FILES 

void ppm_writeppminit ( FILE* fp, int cols, int rows, pixval maxvai, int forceplain ) 

Writetheheader for a portablepixmap file. The forceplain flagforcesa plain-format fileto bewritten, asopposed to a raw- 
format one 

void ppm_writeppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxvai, int forceplain) 

W rite a row from a portable pixmap. 

void ppm_writeppm( FILE* fp, pixel** pixels, int cols, int rows, pixval maxvai, int force-plain) 

Writetheheader and ali data for a portablepixmap. This function combinesppm_writeppminito and ppm_writeppmrow(). 

COLOR NAMES 

This li ne parses an ASC 1 1 color name i nto a pixel: 

pixel ppm_parsecolor( char* colorname, pixval maxvai ) 

The color can bespecified in threeways: asa name, assumi ng that a pointer to an Xll-style color names file was compi led 
in; asan Xll-style hexadecimal number (#rgt>, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb); or asatriplet of decimai floating 
point numbersseparated by commas(r.r,g.g,b.b). 

This line returns a pointer to a stri ng describing thegiven color: 

char* ppm_colorname( pixel* colorP, pixval maxvai, int hexok ) 

If the X 11 color names file isavailable and the color appears in it, that nameis returned. Otherwise, if the hexok flag istrue, 
then a hexadecimal coiorspec is returned; if hexok is false and the X 11 color names file isavailable, then the closest matching 
color is returned; otherwise, it'san error. 

SEEALSO 

pbm(3), pgm(3) 

AUTHOR 

Copyright © 1989, 1991 byTony H ansen and Jef Poskanzer 

localeconv 

ìocaieconv— Getsnumeric formatti ng informati on 
SYNOPSIS 

#include <locale.h> 

struct lconv *localeconf (void) ; 
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D ESC RIPTIO N 

Theiocaieconf () function returns a string to astruct iconv forthecurrent locale. 

CONFO RMSTO 

ThiscommandconformstoANSI C and POSIX.l. 
Linux supports the portable locales C and POSIX and alsotheEuropean Latin-1 ISO -8859-1, and Russian KO 1-8 locales. 
Theprintf o family of functionsmay or may not honorthecurrent locale. 

SEEALSO 

locale(l), localedef (1), strcoll(3), isalpha(3), setlocale(3), strftime(3), locale(7) 

GNU, 25 Aprii 1993 

longjmp 

ìongjmp— N onlocal jump to a saved stack context 
SYNOPSIS 

#include <setjmp.h> 

void longjmp(jmp_buf env.int vai ); 

DESCRIPTION 

ìongjmpo and setjmp(3) areuseful fordealingwith errorsand interruptsencountered in alow-level subroutine of a program, 
ìongjmpo restores the envi ronment saved by the last cali of setjmpo with thecorrespondingenv argument. After long jmpo is 
completed, program execution continuesasif the corresponding cali of setjmpo had just returned thevaluevai. ìongjmpo 
cannot cause 0 to be returned. If ìongjmp isinvoked with a second argument of 0, 1 wi II be returned instead. 

RETURN VALUE 

This function never returns. 

C0NF0RMST0 

POSIX 

NOTES 

POSIX does not specify if the si gnal context wi II berestored or not. If you wantto save restare si gn al masks, use 
sigiongjmp(3). ìongjmpo makes programshard to understand and maintain. If possible, an alternative should beused. 

SEEALSO 

setjmp(3), sigset jmp(2), siglongjmp(2) 

25 N ovember 1994 

lfind, Isearch 

ifind, isearch— Linear search of an array 
SYNOPSIS 

#include <stdlib.h> 

void *lfind(const void * k e y , const void "base, size t "nmemb, 
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size_t si z e , int ( *c o mp a r ) (const void *, const void *)); 

void *lsearch(const void *key, const void * b a s e , size_t *nmemb, 

size_t si z e , int ( *c o mp a r ) (const void *, const void *)); 

D ESC RIPTIO N 

ifindo and isearcho perform a linear search for key in thearray base, which has*nmemb elementsof size bytes each. The 
compari son function referenced by compar isexpected to havetwo argumentsthat pointto the key object and to an array 
member, in that order, and which returnszero if the key object matches the array member, and non-zero otherwise 

If isearcho does notfind a matchingelement, then the key object isinserted at the end of thetable, and *nmemb is 
incremented. 

RETURN VALUE 

ifindo returns a pointer to a matching member of thearray, or null if no match isfound. isearch oreturns a pointer to a 
matching member of thearray, orto thenewly added member if no match isfound. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bsearch(3), hsearch(3), tsearch(3) 

GNU, 17 September 1995 

calloc, malloc, f ree, realloc 

caiioc, mailoc, tree, reailoc— Allocate and freedynamic memory 
SYNOPSIS 

#include <stdlib.h> 

void *calloc ( size_t nmemb, size_t size); 

void *malloc (size_t size); 

void f ree(void *pt r ) ; 

void *realloc (void *ptr, size_t size); 

DESCRIPTION 

canoe o allocates memory for an array of nmemb elementsof size bytes each and returns a pointer to the allocateci memory. 
The memory isset to zero. 

maiioco allocates size bytesand returns a pointer to the allocateci memory. The memory isnotcleared. 

freeo frees the memory space pointed to by ptr, which must havebeen returned by a previ ous cali to maiioco, caiioco or 
reaiioco. If ptr is null, no operation isperformed. 

reaiioco changes the size of the memory block pointed to by ptr to size bytes. The contentswi II beunchanged to the 
minimum of the old and new sizes; newly allocateci memory wi II beuninitialized. If ptr is null, the cali isequivalent to 
maiioc (size); if size isequal to zero, the cali isequivalentto tree(ptr). U nlessptr is null, it must havebeen returned by an 

earlier cali tO mallocO, callocO, or realloco. 

RETURN VALUES 

For canoe o and mailoc o, the value returned is a pointer to the allocateci memory, which issuitably aligned for any kind of 
variable, or null if the request fails. 

freeo returnsno value. 



mbstowcs 

reaiioc oretums a pointer to thenewly allocateci memory, which issuitably ali gned for any kind of vari able and may be 
different from ptr, or null if the request fai Is or if size wasequal to a. If reaiioco fails, the originai block isleft untouched; 
itisnotfreedormoved. 

C0NF0RMST0 

ANSI C 

SEEALSO 

brk(2) 

GNU, 4 Aprii 1993 

mblen 

rabien— D etermi nes the number of bytes in a character 
SYNOPSIS 

#include <stdlib.h> 
int_mblen(const char *s , size_t n); 

DESCRIPTION 

The mbien o function scansthefirst n bytes of the stri ng s and returns the number of bytes in a character. Thembieno 
function isequivalentto 

mbtowc( (wchat t*)0,s,n); 

except thattheshift state ofthembtowco function isnotaffected. 
RETURN VALUE 

The mbien oretums the number of bytes in a character, or -1 if the character is invai id, or 0 if it isaNun stri ng. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEEALSO 

mbstowcs(3), mbtowc(3), wcstombs(3), wctomb(3) 

GNU, 29 March 1993 

mbstowcs 

mbstowcs— C onverts a multi byte stri ng to a wide character stri ng 
SYNOPSIS 

#include <stdlib.h> 

size_t mbstowcs (wchar_t *pwcs, const char *s , size_t n); 

DESCRIPTION 

The mbstowcs 0 function convertsasequenceof multi byte characters from thearray s into asequenceof wide characters and 
stores upto n wide characters in thearray pwcs . 
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RETURN VALUE 

mbstowcso returns the numberof wide characters stored, or -1 if s containsan invalid multibytecharacter. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEEALSO 

mblen(3), mbtowc(3), wcstombs(3), wctomb(3) 

GNU, 29 March 1993 

mbtowc 

mbtowc— C onverts a multi byte character to a wide character 
SYNOPSIS 

#include <stdlib.h> 

int mbtowc (wchar_t *pwc, const char *s , size_t n); 

DESCRIPTION 

The mbtowc) ) function converts a multibytecharacter s, which isno longerthan n bytes, into a wide character and, if pwc is 
not null, stores the wide character in pwc . 

RETURN VALUE 

mbtowc o returnsthenumberof bytesinthemulti byte character, or -1 if the multi byte character is not valid. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEEALSO 

mblen(3), mbstowcs(3), wcstombs(3), wctomb(3) 

GNU, 29 March 1993 

memccpy 

memccpy— C opies memory area 
SYNOPSIS 

#include <string.h> 

void *memccpy(void *d est , const void *s r c , int c, size_t n); 

DESCRIPTION 

The memccpy o function copies no morethan n bytes from memory area src to memory area d e s t , stoppi ngwhen the 
character c isfound. 

RETURN VALUE 

The memccpy o function returns a pointer to the next character in d est after c, or null if c was notfound in the first n 
characters of s r c . 



mancmp 



CONFORMSTO 

SVID 3, BSD 4.3 

SEEALSO 

bcopy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, IOApriI 1993 

memchr 

memchr— Scans memory for a character 
SYNOPSIS 

#include <string.h> 

void *memchr(const void *s,int c, size_t n); 

DESCRIPTION 

Thememchro function scansthe first n bytesof the memo ry area pointed to by s f or the character c. The first byteto match c 
(interpreted asan unsigned character) stopstheoperation. 

RETURN VALUE 

Thememchro function returns a pointer to thematching byteorNuu. if the character does not occur in thegiven memory 
area. 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), rindex(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3) 

GNU, 12 Aprii 1993 

memcmp 

memcmp — Compares memory areas 

SYNOPSIS 

(finclude <string.h> 

int memcmp(const void *sl, const void *s2, size_t n); 

DESCRIPTION 

The memcmp o function compares the firstn bytesof the memory areas si and s2. It returns an integer lessthan, equal to, or 
greater than zero if si isfound, respectively, to be lessthan, to match, orto begreaterthan s2. 

RETURN VALUE 

Thememcmpo function returns an integer lessthan, equal to, or greater than zero if the firstn bytesof si isfound, respec- 
tively, to be lessthan, to match, or begreaterthan the firstn bytesof s2. 
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CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

bcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncmp(3), strncasecmp(3) 

10 Aprii 1993 



memcpy 

memcpy— C opies memory area 
SYNOPSIS 

#include <string.h> 

void *memcpy(void *d e s t , const void *src, size_t n); 

DESCRIPTION 

The memcpy o function copiesn bytesfrom memory area s r c to memory area d e s t . The memory areas may not overlap. Use 
memmove(3) if the memory areas do overlap. 

RETURN VALUE 

The memcpy o function returnsapointertodest. 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

bcopy(3), memccpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, IOApriI 1993 

memfrob 

memfrob— Frobnicates (encrypts) a memory area 
SYNOPSIS 

#include <string.h> 

vcid *memf rob (void *s , size_t n); 

DESCRIPTION 

The memfrob o function encrypts the first n bytesof the memory areas by using exclusiveoR on each characterwith the 
number42.Theeffectcan bereversed by using memfrob) > on theencrypted memory area. 

Notethatthisfunction is not a proper encryption routineasthexoR Constant isfixed, and isonlysuitableforhidingstrings. 
RETURN VALUE 

Thememfrobo function returns a pointer to theencrypted memory area. 



manmove 



C0NF0RMST0 

Thememfrobo function isuniqueto the Linux C Library and GNU C Library. 
SEEALSO 

strf ry(3) 

GNU, 12 Aprii 1993 

memmem 

Locatesa substring 

SYNOPSIS 

#include <string.h> 

void *memmem(const void * n e e d I e , size_t needlelen, 
const void "haystack, size_t haystacklen");" 

DESCRIVO N 

The memmem o function fi nds the fi rst occurrence of the substring need e of length needi e en in thememory area h a y s t a c k of 

length haystacklen. 

RETURN VALUE 

The memmem o function returns a poi nter to thebeginning of the substring, orNULL if the substring isnot found. 
SEEALSO 

strstr(3) 

GNU, 11 Aprii 1993 

memmove 

memmove— C opies memory area 
SYNOPSIS 

#include <string.h> 

void "memmove (void *d est , const void *src, size_t n); 

DESCRIPTION 

Thememmoveo function copiesn bytes from memo ry area s r c to memory area dest . Thememory areasmay overlap. 

RETURN VALUE 

Thememmoveo function returns a pointer to dest . 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 

GNU, 10 Aprii 1993 
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memset 

memset — Fills memory with a Constant byte 
SYNOPSIS 

#include <string.h> 

void *memset(void *s,int c, size_t n); 

D ESC RIPTIO N 

Thememseto function fills the firstn bytesof the memory area poi nted to bes with the Constant byte c. 

RETURN VALUE 

Thememseto function returns a pointer to the memory area s. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

bzero(3), swab(3) 

GNU, 11 Aprii 1993 



mkfifo 

mkfifo— M akesa FIFO special file (a named pipe) 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/stat.h> 

int mkfifo ( const char *pat lina me ,mode_t mode ); 



DESCRIPTION 

mkfifo makesa FIFO special fi le with namepat h na me . mode specifies the FIFO 's permissions. It ismodified by the process's 
umask in theusual way: the permissions of the created file are (mode&umask). 

A FIFO special fileissimilarto a pipe, except that it is created in adifferentway. Instead of beingan anonymous Communi- 
cations channel, a FIFO special fileisentered into thefilesystem by calling mkfifo. 

After you have created a FIFO special fi le in thisway, any processcan open itfor readingor writing, in thesameway asan 
ordì nary file. H owever, it hasto beopen at both endssimultaneously beforeyou can proceed to do any input or output 
operati onson it. 0 pening a FIFO for reading normally blocksuntil someother processopens the same FIFO for writing, 
and viceversa. 

RETURN VALUE 

Thenormal, successful return valuefrom mkfifo is 0. In thecaseof an errar, -1 isreturned (in which case, ermo isset 
appropri atei y). 

ERRORS 

eacces Oneof thedirectoriesin pattinarne did notallow search (execute) permission. 

eexist pathname al ready exists. 



mktanp 




ENAMETOOLONG 

ENOENT 

ENOSPC 
ENOTDIR 
EROFS 

CONFO RMSTO 

POSIX.l 

SEEALSO 

mkfifo(l), read(2), write(2), open(2), close(2), stat(2), umask(2) 

Linux 1.2.13, 3 September 1995 

mkstemp 

mkstemp— C reates a unique tamporary file 
SYNOPSIS 

#include <unistd.h> 

int *mkstemp(char *t empi at e ) ; 

DESCRIPTION 

The mkstemp o function generatesauniquetemporary fi lenamefrom tempi a t e . Thelast sixcharactersof tempi at e must be 
xxxxxx and thesearereplaced with a string that makes the fi lename unique. The file isthen created with mode read/write and 
permissions0666. 

RETURN VALUE 

Themkstempo function returnsthefiledescriptorfd of the temporary file 
ERRORS 

einval Thelast sixcharactersof tempi at e were not xxxxxx. 

eexist The temporary file is not unique. 

C0NF0RMST0 

BSD 4.3 

SEEALSO 

mktemp(3), tmpnam(3), tempnam(3), tmpf ile(3) 

GNU, 3 Apri 1 1993 

mktemp 

mktemp— M akes a unique temporary fi lename 



Eitherthetotal length of pattinarne isgreaterthan path max, oran individuai 
fi lename component has a length greater than namemax. In theGN U system, 
thereisno imposed limiton overall fi lename length, but somefilesystems may 
place limits on the length of a component. 

A directory component in pattinarne does not exist or isa dangling symbolic 
link. 

T he directory or fi lesystem hasno room for the new file. 
A component used asa directory in pattinarne isnot, in fact, a directory, 
pattinarne refersto a read-only filesystem. 
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SYNOPSIS 

(finclude <unistd.h> 

char *mktemp(char *t empi at e ) ; 

D ESC RIPTIO N 

Themktempo function generatesauniquetemporary filmarne from tempi a te. The last sixcharactersof tempi at e must be 
xxxxxx and theseare replaced with a string that makes thefilenameuniqua 

RETURN VALUE 

Themktempo function returns a pointer tot empi at e on success, and null on failure. 
ERRORS 

einval The last sixcharactersof tempiate were not xxxxxx. 

C0NF0RMST0 

BSD 4.3. POSIX dictatestmpnamo. 

SEEALSO 

mkstemp(3), tmpnam(3), tempnam(3), tmpf ile(3) 

GNU, 3 Apri 1 1993 

modf 

modf— Extractssigned integrai and fractional valuesfrom floati ng-poi nt number 
SYNOPSIS 

#include <math.h> 

doublé modf (doublé x, doublé *iptr); 

DESCRIPTION 

T he modf o function breakstheargumentx into an integrai part and a fractional part, each of which hasthesamesign asx. 
Theintegral part isstored in i ptr . 

RETURN VALUE 

T he modf o function returns the fractional part ofx. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

frexp(3), ldexp(3) 

6 Junel993 



asctime, ctime, dif f time, gmtime, localtime, mktime 

asctime, ctime, dif f time, gmtime, localtime, mktime— C Onvert date and time tO ASC 1 1 



asctime, dime, difftime, gmtime, loca Iti me mktime 




SYNOPSIS 

extern char *tzname[2]; 

void tzset() 

#include <sys/types.h> 

char *ctime(clock) 
const time_t "clock; 

doublé difftime (timel , timeS) 
time_t timel ; 
time_t timeB; 

#include <time.h> 

char *asctime(tm) 
const struct tm *tm; 

struct tm *localtime(clock) 
const time_t "clock; 

struct tm *gmtime(clock) 
const time_t "clock; 

time_t mktime (tm) 
struct tm *tm; 

ce . . . -lz 

D ESC RIPTIO N 

ctime convertsa long integer, poi nted to by clock, representi ng the ti me in seconds si nce 00:00:00 UTC, January 1, 1970, 
and returns a pointer to a 26-character stri ng of theform Thu nov 24 18:22:48 1986. (N ote: UTC isCoordinated Universal 
Time.) Ali thefields have Constant width. 

ìocaitime and gmtime return pointersto tm structures, described in the followi ng paragraphs. ìocaitime correetsforthetime 
zone and any timezoneadjustments(such asDaylight Savi ng Ti me in theU nited States). Beforedoingso, ìocaitime cai Is 
tzset (if tzset hasnot been called in thecurrent process). After filling in thetm structure, ìocaitime setsthetmjsdst'th 
element of tzname to a pointer to an ASCII stri ngthat's the ti me zone abbrevi ation to beused with ìocaitime's return value. 

gmtime converts to C oordinated U niversal Time 

asctime convertsa time vai ue contai ned in a tm structure to a 26-character stri ng, asshown in the precedi ngexample, and 
returns a pointer to the string. 

mktime converts the broken-down time, expressed as locai time, in the structure poi nted to by tm into acalendar time value 
with thesameencodingasthatof thevaluesreturned by the time function. The originai valuesof thetm_wday and tm_yday 
componentsof the structure are ignored, and the originai valuesof the other componentsarenot restri cted to their normal 
ranges. (A positive or zero value for tmjsdst causes mktime to presume initially that summer time(for example, D aylight 
SavingTimein the United States) respectively, isor is not in effect for the specified time. A negative value fortm_isdst 
causes the mktime function to atterri pt to divinewhether summer time is in effect for the speci fi ed time.) On successful 
completion, the valuesof the tm_wday and tm_yday components of the structure are set appropri ately, and the other 
componentsareset to represent the specified calendar time, but with their valuesforced to their normal ranges; the final 
value of tm_mday is not set unti I tm_mon and tm_year are determi ned. mktime returns the speci fi ed calendar time; if the calendar 
timecannot be represented, it returns -1. 



FI 



Part III: Library Functions 



difftime returnsthedifferencebetween two calendartimes, (ti mei - t i meo), expressed in seconds. 

Deci arati onsof ali the functions and extemals, and thetm structure, arein the <time.h> headerfile. Thestructure(of type) 
struct tm i ncludesthefollowing fidds: 

int tm_sec; / seconds (0 ■ 60) / 

int tmjnin; / minutes (0 - 59) / 

int tm_hour; / hours (0 - 23) / 

int tmjnday; / day of month (1 -31) / 

int tmjnon; / month of year (0 - 11) / 

int tm_year; / year - 1900 / 

int tm_wday; / day of week (Sunday = 0) / 

int tm_yday; / day of year (0 - 365) / 

int tm_isdst; / is summer time in effect? / 

char tm_zone; / abbreviation of timezone name / 

long tm_gmtoff; / offset from UTC in seconds / 

Thetnwone and tm_gmtoff fiddsexist, and are fi lied in, only if arrangementsto do so weremadewhen the library contai ni ng 
these functions wascreated. There isno guarantee that thesefields will conti nueto exist in thisform in future releasesof this 
code. 

Tm_isdst is non-zero if summer time is in effect. 

Tm_gmtoff is the offset (in seconds) of the time represented from UTC, with positive values indicating east of thePrime 
M eridian. 

FILES 

/usr/iocai/etc/zoneinfo Ti mezone information directory 

/usr/local/etc/zoneinfo/localtime Locai timezonefile 

/usr/local/etc/zoneinfo/posixrules Usedwith PO SIX-StyleTZs 

/usr/iocai/etc/zoneinfo/GMT ForUTC leap seconds 

If /usr/local/etc/zoneinfo/GMT isabsent, UTC leap Seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 

SEEALSO 

getenv(3), newtzset(3), time(2), tzf ile(5) 

NOTES 

The return values poi ntto stati c data; the data isoverwritten by each cali. The tm_zone field of a returned struct tm pointsto 
a stati c array of characters, which will also beoverwritten atthenext cali (and by Calisto tzset). 

Avoid usingout-of-range values with mktimewhen settingup lunch with promptnesssticklersin Riyadh. 



tzset 

tzset— Initializes time conversion information 
SYNOPSIS 



void tzset( ) ; 
ce . . . -lz 



tzset 



FI 



DESCRIPTIOr 



tzset usesthevalueof theenvironment variable tz to set ti me conversi on information used by ìocaitime.lf tz does not 
appear in theenvironment, thebest availableapproximation to locai wall clock ti me, asspecified by the tzfìie(5)-format file 
ìocaitime in the system ti me conversi on information directory, isused by ìocaitime. If tz appearsin theenvironment but its 
valueisa nuli stri ng, Coordinated U ni versai Time (UTC) isused (without leap second correction). If tz appears in the 
environmentand its value is not a nuli stri ng, it isused in oneof thefollowingways: 

If thevaluebeginswith a colon, it isused asa pathnameof afilefrom which to read thetimeconversion information. 

If the value does not begin with a colon, it is first used as the pathnameof afilefrom which to read thetimeconversion 
information, and, if that fi le cannot beread, isused directly asa speci fication of thetimeconversion information. 

When tz isused asa pathname, if it beginswith aslash, it isused asan abso Iute pattinarne; otherwise, it isused asa 
pathnamerelativeto a system timeconversion information directory. Thefile must be in the format speci fi ed in tzfiie(5). 

When tz isused directly asa specificati on of thetimeconversion information, it must havethefollowingsyntax(spaces 
inserted for clarity): 

s t d of f set[ dst [ of f set ] | , rul e] I 



T he elements are as fol lows: 

std and dst 



offset 



r ul e 



Threeor more bytes that are the desi gnation for the standard (std) or 
summer(dst) ti me zone. Onlystd isrequired; if dst ismissing, then 
summer ti me does not apply in this locale. U ppercaseand lowercase 
letters are explicitly allowed. Any charactersexcepta leading colon (:), 
digits, comma (,), minus(-), plus {+), and ASCII N UL are allowed. 
Indicatesthevalueonemust add to thelocal timeto arriveat 
Coordinated U ni versai Time. The off set hastheform: 

h h [ : mm [ : s s ] ] 

Theminutes(mm) and seconds(ss) are optional. Thehour (hh) isrequired 
and may bea single digit. Theof f set followingstd isrequired. If no 
offset followsdst , summer ti me is assumed to beone hour ahead of 
standard ti me. One or more digits may beused; the value isalways 
interpreted asa decimai number. Thehour must bebetween zero and 24, 
and theminutes(and seconds)— if present— between zero and 59. If 
preceded by a "+", the ti me zone shall beeastof the Prime M eridian; 
otherwise, it shall bewest(which may beindicated byan optional 
preceding ■ -"). 

Indicateswhen to changeto and back from summer time. Theru! e has 
theform: 

dot e/t i me , d a t e/t i me 

wherethefirstdate describeswhen thechangefrom standard to summer 
timeoccursand the second date describeswhen the change back happens. 
Each ti me field describeswhen, in current locai time, the changeto the 
othertimeismade. 

The format of date is oneof the following: 
Thed 'th day (0 <=d <=6) of week n of month m of theyear (1 <=n 
<=5, 1 <=m <=12, whereweek 5 means"thelastd day in month m" 
which may occur in eitherthefourth orthefifth week). Week 1 
is the first week in which thed 'th day occurs. Day zero isSunday. 
Thejulian day n (1 <=n <=365). Leap daysarenot counted; that is, in 
ali years— including leap years— February 28 isday 59 and M arch 1 is 
day 60. It is impossibleto explicitly refer to theoccasional February 29. 
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n Thezero-based Julian day (0 <=n <=365). Leap daysarecounted, and it 

ispossibleto referto February 29. 

Mm. n. d Thed'th day (0 <=d <=6) of week n of month m of theyear (1 <=n <=5, 

1 <=m <=12, whereweek 5 means"thelastd day in month m," which 
may occur in either the fourth orthefifth week). Week 1 isthefirst week 
in which thed'th dayoccurs. Day zero isSunday. 
T rietine hasth esame format asoffset exceptthatno leadingsign ("+" 
or"-") isallowed. The default, iftìme isnotgiven, is 02:00:00. 

If no ruie ispresent in tz, therulesspecified by thetzfiie(5)-formatfileposixruies in the system timeconversion 
information directory areused, with the standard and summer timeoffsetsfrom UTC replaced byth ose speci fi ed by the 
offset values in tz. 

For compati bili ty with System V Release3.1, a semicolon (;) may beused to separate the ruie from the restof the speci fi ca- 
tion. 

If the tz environmentvariabledoesnot specify a tzfiie(5)-formatand cannot beinterpreted as a direct speci fi cation, UTC is 
used. 

FILES 

/usr/iocai/etc/zoneinfo T imezone information directory 

/usr/local/etc/zoneinfo/localtìme Locai timezonefile 

/usr/local/etc/zoneinfo/posixrules Used with PO SlX-Style TZS 

/usr/local/etc/zoneinfo/GMT ForUTC leap Seconds 

If /usr/local/etc/zoneinfo/GMT isabsent, UTC leap Seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 

SEEALS0 

getenv(3), newctime(3), time(2), tzf ile(5) 

on_exit 

on exit— Registers a function to becalled at normal program terminati on 
SYN0PSIS 

#include <stdlib.h> 

int on_exit(void (*function) (int , void *), void *arg); 

D ESC RIFTI0 N 

Theon_exito function registers the given function to becalled at normal program termi nation, whether viaexit(2) or via 
return from the program's mai n. The function ispassed theargumentto exit(3) and thearg argument from on_exit(). 

RETURN VALUE 

Theon exito function returnsthevalueo if successful; otherwise, thevalue-1 isreturned. 
SEEALS0 

exit(3), atexit(3) 

GNU, 2 Aprii 1993 



opendir 

opendir— 0 pens a di rectory 
SYNOPSIS 

#include <sys/types.h> 
#include <dirent.h> 
DIR "opendir (const char *name); 

D ESC RIFTIO N 

TheopendirQ function opensa directory stream correspondingto the di rectory name, and returnsapointerto the directory 
stream. Thestream is positioned at the first entry in the di rectory. 

RETURN VALUE 

Theopendiro function returnsapointerto the di rectory stream orNULL if an errar occurred. 



ERRORS 

eacess P ermi ssion denied 

emfile Too many f i le descri ptors i n useby process 

enfile Too many fi les are currently open in the system 

enoent Directory doesnotexist, ornane isan empty stri ng 

enomem Insufficient memory to complete the operation 

enotdir name is not a directory 



C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEEALSO 

open(2), readdir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

11 Junel995 



parsedate 




parsedate 

parsedate— Converts ti me and date string to number 
SYNOPSIS 

#include <sys/types.h> 

typedef struct_TIMEINFO f 

time_t time; 

long usec; 

long tzone; 

} TIMEINFO; 

time_t 

parsedate(text, now) 
char *text; 
TIMEINFO *now; 

DESCRIPTION 

parsedate converts many common ti me specificati onsinto the number of secondssincetheepoch, that is, atìme_t; see 

time(2). 
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parsedate return s the time, or -1 on errar, text isacharacter stri ng contai ni ngthetimeand date, now is a pointer to the time 
that should beused for cai culati ng relative dates. If nowisNULL, then GetTimeinfo in iibinn(3) isused to obtain thecurrent 
ti me and ti me zone. 

Thecharacter stri ng consistsof zero or more specifi cations of the followingform: 

time A ti me Of day, which isof theform hh[:mm[:ss ]] [meri di an ] [zone ]Or hhmm 

[meri di an ] [zone ]. If no meridian is specifi ed, hh isinterpreted on a24-hour 
clock. 

date A specific month and day with optional year. T he acceptable formate are 

mm/dd [/ yy ], yyyy /mm/dd, mont hna me dd[, yy],dd mo n t h n a me [yy],and 
day.ddmont hnameyy, and day, dd monthname yy . T he default year ÌS the Current 

year. If theyear is lessthen 100, then 1900 isadded to it; if it islessthen 21, 
then 2000 isadded to it. 

relative time A specification relativeto thecurrent time. Theformat isnumber unit; 

acceptable unite are year, month, week, day, hour, minute (ormin), and second 

(orsec).Theunitcan bespecified as a singular or plural, asin 3 weeks. 

Theactual date is calculated accordingto thefollowing steps. First, any absolute date or time isprocessed and converted. 
Using that time as the base, day-of-week specifications are added. Next, relative specifications are used. If adateordayis 
specifi ed, and no absolute or relativetimeisgiven, midnight isused. Finally, acorrection isapplied so that the correct hour 
of the day isproduced after allowi ng for D aylight Savi ngsT ime differences. 

parsedate ignores case when parsi ng ali words; unknown wordsaretaken to beunknown timezones, which aretreated as 
GMT. Thenamesof themonthsand daysof theweek can be abbreviate^ to th ei r f i rst th ree I etters, with optional trailing 
period. Peri ods are ignored in any timezoneor meridian values. 

BUGS 

parsedate does not accept ali desi rable and unambiguousconstructions. Semanti cally incorrect dates such as'Tebruary 31" 
areaccepted. 

D aylight SavingsTimeisalwaystaken asaone-hourchangethat iswrong for some places. The D aylight Savi ngsT ime 
correction can get confused if parsi ng a time within an hour of when thereckoning changes, or if given a partial date. 

HIST0RY 

Originally written by Steven M . Bellovin (smb9research.att.com) whileat theU ni versity of N orth C arali naat Chapel Hill 
and distributed under the namegetdate. 

A major overhaul wasdoneby Ri eh $alz (rsaiz@bbn.com) andjim Berets( jberets9bbn.com) in August, 1990. 

It wasfurther revised (primarily to remove obsolete construets and timezonenames) a year later by Rich (now 
rsaiz@osf.org) for I nterN etN ews, and the name was changed. 

SEEALSO 

date(l), ctime(3), libinn(3), time(2) 

perror 

perror— Printsasystem errar message 
SYNOPSIS 

#include <stdio.h> 

void perror(const char *s); 

#include <errno.h> 



popen, pelose 



const char *sys_errlist[ ] ; 
int sys_nerr; 

D ESC RIPTIO N 

The routine perroro producesa messageon the standard error output, descri bing the last errar encountered duringa cali to 
a system or library function. Theargument string s isprinted first, then a colon and a blank, then themessageand a newline. 
To beof most use, theargument string should i nclude the nameof the function that incurred the error. The error number is 
taken from theexternal variable e r r no, which isset when errorsoccur but not cleared when nonerroneouscallsaremade. 

Theglobal error list sys_ermst[] indexed by ermo can beused to obtain the error messagewithout the newline The largest 
message number provided in thetableissys_nerr -1. Becareful when directly accessing this list becausenew error values 
may not have been added to sys_emist [ ] . 

When a system cali fails, it usually returns -1 and sets the variable err no to a value descri bing what went wrong. (These values 
can befound in <errno.h>.) M any library functionsdo likewise. Thefunction perroro servesto translate this error code into 
human-readableform. N otethat ermo isundefined after asuccessful library cali. This cali may well change this variable, 
even though it succeeds, for example, becauseit internally used someother library function that fai led. Thus, if afailing cali 
isnot immediately followed byacall to perror.the value of ermo should besaved. 

CONFO RMSTO 

ANSI CBSD 4.3, POSIX.X/OPEN 

SEEALSO 

strerror(3) 

16 May 1996 

popen, pelose 

popen, pelose— PrOCeSS I/O 

SYNOPSIS 

#include <stdio.h> 

FILE *popen(const char "command, const char *t y p e ) ; 
int pclose(FILE *st ream) ; 

DESCRIPTION 

The popen o function opensa processby creati ng a pipe, forking, and invoking the shell. Becausea pipeisby definition 
unidi rectional, thetype argument may specify only reading or writing, not both; the resulti ng stream iscorrespondingly 
read-only orwrite-only. 

Thecommand argument is a pointer to a nul I-termi nated string contai ni ng a shell command line. This command ispassed to 
/bin/sh using the-c flag; interpretati on, if any, isperformed by the shell. The mode argument is a pointer to a null- 
termi nated string which must beeither r for reading or w for writing. 

The return value from popeno isanormal standard I/O stream in ali respeetssavethat it must beclosed with pcioseo rather 
than fcioseo. W riting to such a stream writesto the standard input of thecommand; the command's standard output isthe 
same as that of the process that called popeno, unlessthisisaltered by thecommand itself. Conversely, reading from a 
"popened" stream reads the command's standard output, and the command's standard input is the same as that of the 
process that called popen. 
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N otethat output popen streams are fully buffered by default. 

T he pelose function waitsfortheassociated processto terminate and returns the exit status of the command asreturned by 

wait4. 

RETURN VALUE 

The popen function returns null if the fork(2) or pipe(2) cai I s fai I , or if it cannot allocate memory. 

The pelose function returns -1 if stream is not associateci with a"popened" command, if stream already "pclosed," orifwait4 
returns an errar. 

ERRORS 

The popen function does not reliably set ermo. (Isthistruefor Linux?) 
BUGS 

The standard input of a command opened for readingshares itsseek offset with the process that called popen o; therefore, if 
the originai process hasdone a buffered read, the command's input positi on may not beasexpected. Similarly, the output 
from a command opened for writing may become intermi ngled with that of the originai process. The lattercan beavoided 
by callingffiusn(3) before popen. 

Fai Iure to executetheshell is i ndi sti nguishable from the shell's fai Iure to execute command, or an immediate exit of the 
command. Theonly hint isan exit statusof 127. (Isthistrue under Linux?) 

Thefunction popeno always calls sh, nevercallscsn. 
HISTORY 

A popen o and a pelose o function appeared in Version 7 AT&T UNIX. 
SEEALSO 

fork(2), sh(l), pipe(2), wait4(2), fflush(3), fclose(3), fopen(3), stdio(3), system(3), fclose(3), fopen(3), stdio(3), system(3). 

BSD man page, 17 M ay 1996 



printf , f printf , sprintf , snprintf , vprintf , vf printf , 
vsprintf, vsnprintf 

printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf— Formatted Output COnversion 

SYNOPSIS 

#include <stdio.h> 

int printf ( const char *f o r ma t , ...); 

int fprintf ( FILE *s t r e a m, const char *f o r ma t , . . . ) ; 

int sprintf ( char *str, const char *f o r ma t , ...); 

int snprintf) char *str, size_t size, const char 'format, ...); 

#include <stdarg.h> 

int vprintf) const char *f o r ma t , va_list ap); 

ant vfprintf( FILE *s t r e a m , const char *f or ma t ,va_list ap); 

int vsprintf( char *str, char *f o r ma t , va_list ap); 

int vsnprintf) char *str, size_t size, char *f or mat ,va_list ap); 



printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf 




DESCRIVO N 

The printf family offunctions produce output accordi ngto a format , asdescribed in thefollowing paragraphs The 
functions printf and vprintf write output to stdout, the standard output st r eam; fprintf and vfprintf write output to the 
given output str eam; sprintf, snprintf, vsprintf, and vsnprintf writeto the character stri ng s t r . 

These functions write the output under the control of af or mat stri ng that specifies how subsequent arguments (or arguments 
accessed via the variable-length argumentfacilitiesof stdarg(3)) areconverted for output. 

These functions return thenumber of characters printed (not includi ng the trai li ng \o used to end output to strings). 
snprintf and vsnprintf do not write morethan aze bytes (includingthe trai ling \e), and return -1 if the output was 
truncated dueto thislimit. 

Thef or mat stri ng iscomposed of zero or more di recti ves: ordinary characters (not %), which arecopied unchanged to the 
output stream; and conversion speci fi cations, each of which resultsin fetchingzero or more subsequent arguments. Each 
conversion specifi cation isintroduced by the character %. The arguments must correspond properly (after type promotion) 
with the conversion specifier. After the%, zero or more of thefollowing flags appear in sequence: 

# Specifying that the valueshould beconverted to an alternateform. Forc, d, i, n, p, s, and u 

conversi ons, thisoption has no effect. Foro conversi ons, the precision of thenumber isincreased to 
force the first character of the output stri ng to a zero (except if azero valueis printed with an explicit 
precision of zero). Forx and x conversions, a non-zero result has the stri ng 0x (or ex for x 
conversi ons) prepended to it. For e, e, f, g, and g conversions, the result wi II always contai n a decimai 
point, even if no digitsfollow it (normally, a decimai point appears in the resultsof those conversions 
only if a digit follows). For g and g conversions, trailingzerosarenot removed from the result asthey 
would otherwisebe. 

0 Specifying zero padding. Forali conversions except n, theconverted valueis padded on the left with 
zeros rather than blanks. If a precision is given with a numeric conversion (d, i, o, u, i, x, and x), the 
0 flag isignored. 

(a negative field width flag) Indicates theconverted valueis to beleft adjusted on thefield boundary. 
Except for n conversions, theconverted valueis padded on the ri ght with blanks, rather than on the 
left with blanks or zeros. A - overrides a 0 if both are given. 

1 1 (a space) Specifying that a blank should be left before a positive number produced byasigned 

conversion (d, e, e, f, g, g, or i). 
+ Specifying that a sign always be pi aced before a number produced by asigned conversion. 

A + overrides a space if both are used. 

Specifying that in a numerical argument the output isto begrouped if the locale information 
indicates any. N otethat many versi ons ofgcc cannot parse thisoption and will issuea warning. 
An optional decimai digit stri ng specifying a minimum field width. If theconverted valuehasfewer 
characters than thefield width, it will be padded with spaceson the left (or right, if theleft- 
adjustment flag hasbeen given) to fili out thefield width. 

An optional precision, in theform of a period (.) followed by an optional digit stri ng. If the digit 
stri ng is omitted, the precision istaken as zero. Thisgives the minimum number of digitsto appear 
for d, i, 0, u, x, and x conversions; thenumber of digitsto appear after the deci mal point for e, e, and 
f conversions; the maximum number of significant digitsfor g and g conversions; or the maximum 
number of characters to be printed from a stri ng for s conversions. 

The optional character n, specifying that a followingd, i, 0, u, x, or x conversion correspondsto a 
short int orunsigned short int argument, or that a following n conversion correspondsto a poi nter 
to a short int argument. 

The optional character 1 (eli) specifying that a followingd, i, 0, u, x, or x conversion appliesto a 
pointer to aiong int orunsigned long int argument, or that a following n conversion correspondsto 
a pointer to a long int argument. Linux providesa non-AN Sl-compliant useof two 1 flags as a 
synonym to q or l. Thus, 11 can beused in combination with float conversions. Thisusageis, 
however, strongly discouraged. 
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Thecharacter l specifying that afollowing e, e, f, g, or g conversion correspondsto a long doublé 
argument, or afollowing d, i, o, u, x, or x conversion correspondsto a long longargument. N otethat 
long long isnot specified in AN SI C and thereforenot portableto ali architectures. 
Theoptional character q. Thisisequivalentto l. Seethe"Standards" and "Bugs" sectionsfor 
comments on the use of 11, l, and q. 

A z character specifying that the following integer (d, i, o, u, i, x, and x) conversion correspondsto a 
sizet argument. 

A character that specifies the type of conversion to be applied. 

A field width or precision, or both, may beindicated by an asterisk * instead of a digit string. In thiscase, an int argument 
suppliesthefield width or precision. A negative field width istreated asa left adjustment flagfollowed by a positive field 
width; a negative precision istreated asthough itweremissing. 

Theconversion speci fi ers and their meaningsareasfollows: 

diouxx The int (or appropriate vari ant) argument isconverted to signed decimai (d and i), 

unsigned octal (o), unsigned decimai (u), or unsigned hexadecimal (x and x) notation. The 
letters abcdef areused forx conversions; the letters abcdef areused forx conversions. The 
precision, if any, gives the minimum number of digits that must appear; if theconverted 
valuerequiresfewer digits, it ispadded on the left with zeros. 

eE Thedoubie argument isrounded and converted in thestyle [-]d.ddde\dd wherethere is 

one digit before the deci mal-poi nt character and the number of digits after it isequal 
to the precision; if the precision ismissing, itistaken as6; if the precision iszero, no 
deci mal-poi nt character appears. An e conversion usestheletter e (rather than e) to 
introduce the exponent. T he exponent always contai ns at least two digits; if the value is 
zero, the exponent isOO. 

t Thedoubie argument isrounded and converted to decimai notation in thestyle 

[ - ] d d d . ddd, where the number of digits after thedecimal-point character isequal to 
the precision specification. If the precision ismissing, itistaken as6; if the precision is 
explicitly zero, no deci mal-poi nt character appears. If a decimai point appears, at least one 
digit appears before it. 

g Thedoubie argument isconverted in style f ore (or e forG conversions). The precision 

specifies the number of significant digits. I f the precision ismissing, 6 digits aregi ven; if 
the precision iszero, it istreated asl. Style e isused if the exponent from its conversion is 
lessthan negati ve 4 or greaterthan or equal to the precision. Trai li ng zeros are removed 
from thefractional partof the result; a decimai point appears only if it isfollowed byat 
least onedigit. 

c The int argument isconverted to an unsigned cbar, and the resulti ng character iswritten. 

s The char * argument is expected to be a pointer to an array of character type (pointer to a 

string). Charactersfrom the array are written upto (but not including) aterminatingNUL 
character; if a precision is specified, no more than the number specified are written. If a 
precision isgiven, no nuli character need bepresent; if the precision isnot specified, oris 
greater than thesizeof the array, the array must contai n aterminatingNUL character. 

p Thevoid * pointer argument isprinted in hexadecimal (asif by %#x or %#ix). 

n T he number of characters written so far isstored into the integer indi cated bythemt * 

(orvariant) pointer argument. N o argument isconverted. 

% A % iswritten. N o argument isconverted. The complete conversion specification is%%. 

In no casedoesa nonexistent or small field width cause truncation of a field; if the result of a conversion iswider than the 
field width, thefield isexpanded to contain theconversion result. 



995 



printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf 
EXAMPLES 

To print a date and ti me in theform "Sunday, July 3, 10:02," whereweekday and month arepointersto stringa 

(finclude <stdio.h> 

fprintf (stdout, "%s, %s %d, %.2d:%.2d\n" , 
weekday, month, day, hour, min); 

To print tofive decimai places: 

#include <math.h> 
#include <stdio.h> 

fprintf (stdout, "pi = %.5f\n", 4 * atan(1.0)); 

To allocate a 128-byte stri ng and print into it: 

#include <stdio.h> 
#include <stdlib.h> 
#include <stdarg.h> 

char *newf mt(const char *fmt, ...) 
{ 

char *p; 
va_list ap; 

if ((p = malloc(128)) == NULL) 

return (NULL); 
va_start(ap, fmt); 
(void) vsnprintf (p, 128, fmt, ap); 
va_end(ap) ; 
return (p); 

} 

SEEALSO 

printf(l), scanf(3) 

STANDARD S 

The fprintf, printf, sprintf, vprintf, vfprintf, and vsprintf functions conform to AN SI C 3.159-1989 ("ANSI C"). 

Theq flag is the BSD 4.4 notati on foriong long, whileu ortheusageof l in integer conversions isthe GNU notati on. 

The Linux versi on of these functions is based on theGN U ìibio library. Takea look at the info documentation of GN U 
libo {gli bc-1.08) for a more concise descri ption. 

BUGS 

Somefloating point conversions under Linux cause memory leaks. 

Ali functions are fulIyAN SI C 3.159-1989 conformant, but provide the additional flagsq, z, and 1 aswell asan additional 
behavior of theL and ì flags. Thelatter may beconsidered to bea bug, asit changes the behavior of flags defined in AN SI 
C 3.159-1989. 

Theeffect of paddi ng the %p format with zeros(either by the 0 flag or by speci fying a precisioni, and thebenign effect (that 
is, none) of the # flag on %n and %p conversions, aswell as nonsensi cai combi nations that are not standard; such combinations 
should beavoided. 

Some combi nations of flags defined by AN SI C are not making sense(for example, %Ld). Whilethey may haveawell-defined 
behavior on Linux, thisneed not to beso on other archi tectures. Therefore, it usually is better not to use flags that are not 
defined by AN SI C at ali; in other words, that use q instead of l in combi nation with diouxx conversions or 11. 

Theusageof q isnot thesameason BSD 4.4, asit may beused in float conversions equi valently to l. 
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Becausesprintf and vsprintf assume an infinitely long stri ng, callersmust becareful notto overflow theactual space; thisis 
often impossibleto assure. 

Linux man page 28 January 1996 



psignal 

psignai— Printssignal message 



SYNOPSIS 

#include <signal.h> 

void psignal(ìnt sig, const char *s); 

extern const char "const sys si gl i st [] 

D ESC RIPTIO N 

Thepsignaio function displays a message on stderr consistingof thestring s, a colon, a space, and a stri ng describi ng the 
signal number sig. If sig isinvalid, the message di splay ed will indicate an unknown signal. 

Thearraysys sigiist holds the signal description strings indexed by signal number. 

RETURN VALUE 

Thepsignaio function returns no value 

C0NF0RMST0 

BSD 4.3 

SEEALSO 

perror(3), strsignal(3) 

GNU, 13 Aprii 1993 

putenv 

putenv— Changesor addsan environment variable 
SYNOPSIS 

#include <stdlib.h> 

int putenv(const char *string); 

DESCRIPTION 

Theputenvo function addsor changes the value of environment variables. The argument stri ng isof theform nane = vai uè. 
I f n a me does not al ready exist in the environment, then string isadded to the environment. If nane doesexist, then the value 
of nane i n the environment ischanged to «ai ne. 

RETURN VALUE 

Theputenvo function returns zero on success, or -1 if an errar occurs. 



ERRORS 

ENOMEM 



Insufficient space to allocate new environment 



fputc, fputs, putc, putchar, puts 




CONFORMSTO 

SVID 3, POSIX, BSD 4.3 

SEEALSO 

getenv(3), setenv(3), unsetenv(3) 

GN U, 8 Aprii 1993 

putpwent 

putpwent—W ritesa password file entry 
SYNOPSIS 

#include <pwd.h> 
#include <stdio.h> 
#include <sys/types.h> 

int putpwent(const struct passwd * p , FILE* s t r ea m) ; 

D ESC RIPTIO N 

Theputpwento function writes a password entry from thestructurep i n the fi le associateci with stream. 
The passwd structure isdefined in <pwd.h> asfollows: 

struct passwd { 

char *pw_name; 

char *pw_passwd; 

uid_t pw_uid; 

gid_t pw_gid ; 

char *pw_gecos; 

char *pw_dir; 

char *pw_shell; 

}; 

RETURN VALUE 

Theputpwento function returnsaon success, or -1 if an error occurs. 
ERRORS 

einval Invalid (null) argument given 
CONFORMSTO 

SVID 3 

SEEALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), getpw(3) 

GNU, 9 Apri 1 1993 



* user name */ 

* user password */ 

* user id */ 

* group id */ 

* real name */ 

* home directory */ 

* shell program */ 



fputc, fputs, putc, putchar, puts 

fputc, fputs, putc, putchar, puts— 0 utput of characters and strings 
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SYNOPSIS 

#include <stdio.h> 

int fputc(int c ,FILE*st r eam) ; 

int fputs(const char *s , FILE*s t r ea iti) ; 

int putc(int c , FILE *s t r e a m) ; 

int putchar(int c ) ; 

int puts(char *s ) ; 

int ungetc(int c , FILE *s t r e a m) ; 

D ESC RIPTIO N 

fputco writesthecharacter c, cast to an unsigned citar, to stream. 
fputso writes the stri ng s to stream, without itstrailing \o. 

putco isequivalent to fputco except that it may beimplemented asa macro thatevaluates stream morethan once. 

putchar(c ); is equivalent to putc(cstdout). 

putso writes the string s and a trailing newlineto stdout. 

Calisto the functions described herecan bemixed with each other and with Calisto other output functions from thestdio 
li brary for the same output stream. 

RETURN VALUES 

fputco, putco, and putcharo return thecharacterwritten asan unsigned char castto an int or eof on errar, 
putso and fputso return a non-negative number on success, or eof on errar. 

CONFO RMSTO 

ANSI C, POSIX.l 

BUGS 

It isnot advisableto mix Calisto output functions from thestdio library with low-level Calisto writeo for the file descriptor 
associ ated with the same output stream; the results wi II beundefined and very probably notwhatyou want. 

SEEALSO 

write(2), fopen(3), fwrite(3), scanf(3), gets(3), fseek(3), ferror(3) 

GNU, 4 Aprii 1993 



qio 

qio— Q uick I/O part of I nterN etN ews I i brary 
SYNOPSIS 

#include "qio.h" 
QIOSTATE * 
QI0open(nante, size) 
char *name; 
int size; 

QIOSTATE * QIOfdopen(fd, size) 

int fd; 

int size; 

void QlOclose(qp) 

QIOSTATE *qp; 




char * QlOread(qp) 
QIOSTATE *qp; 
int QlOlength(qp) 
QIOSTATE *qp; 
int QlOtoolong(qp) 
QIOSTATE *qp; 
int QlOerror(qp) 
QIOSTATE *qp; 
int QlOtell(qp) 
QIOSTATE *qp; 
int QlOrewind(qp) 
QIOSTATE *qp; 
int QlOfileno(qp) 
QIOSTATE *qp; 

DESCRIVO N 

Theroutinesdescribed in thismanual page are part of the InterN etN ews library, iit>inn(3). They areused to provide quick 
read access to files. ThelettersQio stand for Quick I/O. 

Qioopen opens the fi le na me for reading. It usesa buffer of size bytes, which mustalso belarger then the longest expected line. 
T he header fi le defines the Constant qio_buffer as a reasonable default. If size is zero, then oioopen will cali stat(2) and use 
thereturned block size; if that fails it will use qio_buffer. It returns null on errar, or a pointer to a handleto beused in other 
cai Is. Qiofdopen performs the samefunction exceptthatfd refersto an already-open descriptor. 

oiociose closes the open file and releases any resourcesused by it. 

oioread returns a poi nter to thenext line in the file. The trai li ng newl ine will bereplaced with a \a. If eof isreached, an errar 
occurs, or if the li ne is longer than the buffer, oioread returns null. 

After a successful cali to oioread, oioiength will return the length of the current line 

Thefunctionsoiotooiong and oioerror can becalled after oioread returns null to determine if therewasan errar, or if the 
linewastoo long. If oiotooiong returns non-zero, then the current linedid not fit in the buffer, and thenext cali to oioread 
will try read therest of the line. Long linescan only bediscarded. If oioerror returns non-zero, then a serious I/O errar 
occurred. 

oioteii returns the iseek(2) offset at which thenext linewill start, 
oiorewind sets the read pointer back to thebeginningof the fi le 
oiofiieno returnsthedescriptor of theopen file. 

oioiength, oiotooiong, oioerror, Qioteii, and oiofiieno are implemented as macrosdefined in the header file. 
EXAMPLE 

QIOSTATE *h; 
long offset; 
char *p; 

h = QIOopen("/etc/motd" , QIO_BUFFER ) ; 

for (offset = QlOtell(h); (p = QlOread(h)) != NULL; offset = QlOtell(h)) 
printf("At %ld, %s\n", offset, p); 
if (QlOerror(h)) { 

perror( "Read error" ) ; 

exit(1); 

} 

QlOclose(h) ; 



HI STORY 

W ritten by Rich $alz (rsaizeuunet.uu.net) for InterN etN ews. 
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qsort 

qsort— Sorts an array 
SYNOPSIS 

#include <stdlib.h> 

void qsort(void *b a s e , size_t nmemb, size_t s i z e , int ( *c o mp a r ) 
(const void *, const void *)); 

D ESC RIFTIO N 

Theqsorto function sorts an array with nmemb elementsof sizes ze.Thebaseargumentpointsto the start of the array. 

Thecontentsof the array are sorted in ascendi ngorder accordi ngto a comparison function pointed to by compar, which is 
called with two argumentsthat pointto theobjects beingcompared. 

The comparison function must return an integer lessthan, equal to, or greater than zero if thefirst argument isconsidered to 
berespectively lessthan, equal to, or greater than thesecond. If two members compare as equal, theirorder in the sorted 
array isundefined. 

RETURN VALUE 

Theqsorto function returnsno value. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

sort(1) 

GNU, 29 March 1993 

raise 

raise— Sendsasignal tothecurrent process 
SYNOPSIS 

#include <signal.h> 
int raise (int s i g ) ; 

DESCRIPTION 

The raise function sendsasignal to thecurrent process. It i s equi vai entto 

kill(getpid( ) ,s i g ) 

RETURN VALUE 

Zero on success, non-zero for fai Iure. 

C0NF0RMST0 

ANSI C 

SEEALSO 

kill(2), signal(2), getpid(2) 

GN U , 31 August 1995 



rand, srand 

rana, srand— Random number generator 
SYNOPSIS 

#include <stdlib.h> 
int rand(void); 

void srand(unsigned int seed); 

D ESC RIFTIO N 

T he rand o function returnsa pseudo-random integer between 0 and randjiax. 

The srand 0 function setsitsargument as the seed fora new sequenceof pseudo-random integersto be returned by rando . 
Thesesequencesarerepeatableby callingsrando with thesameseed value. 

If no seed value isprovided, the rand 0 function isautomatically seeded with a value of 1. 
RETURN VALUE 

T he rand 0 function returnsa value between 0 and rand_max. The srand 0 returnsno value. 
NOTES 

Theversionsof rando and srando in the Linux C Library use the same random number generator as random) ) and 
srandomo, so the lower-order bitsshould beas random asthehigher-order bits. H owever, on older rando implementations, 
thelower-order bits are much less random than thehigher-order bits 

In N umerical Recipesin C : T he Art of Sdentific Computing (W illiam H . Press, Brian P. Flannery, Saul A. Teukolsky, W illiam 
T. Vetterling; N ew York: Cambridge University Press, 1990, first ed, p. 207), thefollowing commentsaremade: 

"If you wantto generate a random integer between 1 and 10, you should alwaysdo itby 

j=1+(int) (10.0*rand()/(RAND+MAX+1 .0) ); 

and never by anything resembling 

j=1+((int) (1000000. 0*rand()) % 10); 

(which uses lower-order bits)." 

Random-number generation isacomplextopic. TheNumericai Recipes in c book(seeprecedingreference) providesan 
excellent discussion of practical random-number generation issuesin Chapter7, "Random Numbers." 

Fora more theoreti cai discussion that also covers many practical issues in depth, pleaseseeChapter 3, "Random Numbers," 
in DonaldE. Knuth'sTheArtof Computer Programming, Volume2 (Seminumerical Algorithms), 2nd ed.; Reading, 
M assachusetts: Addison-Wesley Publishing Company, 1981. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

random(3), srandom(3), initstate(3), setstate(3) 

GNU, 18 May 1995 



random, srandom, initstate, setstate 




random, srandom, initstate, setstate 

random, srandom, initstate, setstate— Random number generator 



302 Partili: Library Functions 
SYNOPSIS 

«include <stdlib.h> 

long int random(void) ; 

void srandom(unsigned int s e e d ) ; 

char *initstate (unsigned int seed, char "state, int n); 
char *setstate(char "state); 

DESCRIPTION 

The randomo function uses a nonlinear additive feedback random number generator employing a default table of size 31 long 
integersto return successive pseudo-random numbersin therangefrom oto rand_max. Theperiod of thisrandom number 
generator isvery large, approximately 16*( (2**31 )-i). 

Thesrandom() function sets its argument as the seed for a new sequenceof pseudo-random integersto bereturned by 
randomo.Thesesequencesarerepeatableby callingsrandomo with thesameseed value. If no seed valueisprovided, the 
randomo function is automatically seeded with a value of 1. 

Theinitstateo function allowsa state array stat e to beinitialized for useby random 0. The size of the state array n isused by 
initstateo to decide how sophisticated a random number generator it should use— the larger the state array, the better the 
random numberswill be. seed istheseed fortheinitialization, which specifies a starting poi nt for the random number 
sequence, and providesforrestartingatthesamepoint. 

Thesetstateo function changes the state array used by the randomo function. The state array state isused for random 
number generation until thenext cali to initstateo or setstateo. state must first havebeen initialized using initstateo. 

RETURN VALUE 

The randomo function returnsavaluebetween 0 and rand_max. Thesrandomo function returns no value.The initstateo 
and setstateo functions return a pointer to the previ ous state array. 

ERRORS 

einval A state array of lessthan 8 byteswasspecified to initstateo. 

NOTES 

Current "opti mal" valuesfor the size of the state array n are 8, 32, 64, 128, and 256 bytes; other amountswill berounded 
down to thenearest known amount. Using lessthan 8 bytes will cause an errar. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

rand(3), srand(3) 

GNU, 28 March 1993 

readdir 

readdir— Reads a directory 
SYNOPSIS 



«include <sys/types.h> 

«include <dirent.h> 

struct dirent *readdir(DIR *dir); 



readv, writev 



DESCRIPTION 

The readdir( ) function returns a pointer to a dirent structure representi ng the next directory entry in the directory stream 
pointedto bydi r. It returns null on reachi ng the end-of-file or if an errar occurred. 

Thedata returned byreaddiro isoverwritten by subsequent Calisto readdiro for the sam e directory stream. 

Accordingto POSIX, thedirent structure contai ns a field char_d_name[] of unspecified size, with at most name_max characters 
precedi ng the termi nati ng null character. Useof other fieldswill harm theportability of your programs. 

RETURN VALUE 

The readdiro function returns a pointer to a dirent structure, or null if an errar occurs or end-of-fileisreached. 
ERRORS 

ebadf Invalid di rectory stream descriptor dir 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEEALSO 

read(2), opendir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

22 Aprii 1996 



readv, writev 

readv, writev— Readsor writesdata into multiple buffers 
SYNOPSIS 

#include <sys/uio.h> 

int readv(int filedes, const struct iovec *v e c t o r , 
size_t count ) ; 

int writev(int filedes, const struct iovec *v e c t or , 
size_t count ) ; 

DESCRIPTION 

The readv o function reads count blocksfrom the fi le associ ated with the fi le descriptor fi i edes into the multiple buffers 
described byvector . 

The writev o function writesat most count blocks described by vect or to the fi le associ ated with the file descriptor fi i edes. 
The pointer vect or pointsto a struct iovec defined in «sys/uio.n>as 

struct iovect 
{ 

void "iovbase; /* Starting address */ 
size_t iov_len; /* Number of bytes */ 

> ; 

Buffers are processed in theorder vector[0], vector[i ], . . . vector[ count]. 

The readv o function works just like read(2) exceptthat multi pie buffers are fi II ed. 

T he writev o function works just likewrite(2) except that multiple buffers are written out. 

RETURN VALUES 

Thereadvo function returnsthe number of bytes or -1 on errar; thewritevo function returnsthe number of bytes written. 
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ERRO RS 

Thereadvo and writevo functionscan fail and set ermo to thefollowing values: 
ebadf fd is not a valid file descri ptor. 

einval fd isunsuitablefor reading (for readvo) or writing (for writevo). 

efault buf isoutsidetheprocesses' addressspace. 

eagain N onblocking I/O had bean selected in the open o cali, and reading or writing could not be 

doneimmediately. 

eintr Readingorwritingwasinterrupted beforeany data was tran sferred. 

CONFO RMSTO 

unknown 

BUGS 

It isnot advisableto mix Calisto functions li ke readvo or writevo, which operate on fi le descri ptors, with the functions 
from thestdio library; the results will beundefined and probably not what you want. 

SEEALSO 

read(2), write(2) 

GNU, 25 Aprii 1993 



realpath 

reaipath— Returnsthecanonicalized absolutepathname 
SYNOPSIS 

#include <sys/param.h> 
#include <unistd.h> 

char *realpath(char *path, char resolved_path[]) ; 

DESCRIPTION 

reaipath expandsall symbol ic links and resolvesreferencesto / ./, / . ./ and extra / charactersin the nul I-termi nated string 
named by path and stores the canoni calized absolutepathname in the buffer of sìz6maxpathlen named by resoived_patn. The 
resulting path will haveno symbolic link, / ./, or / . ./ components. 

RETURN VALUE 

If there isno error, it returns a pointer to the resoived_patn. 

Otherwise, it returns a null pointer and places in resoived_patn theabsolute pathnameof the path component that could not 
beresolved. Theglobal variableerrno i s set to indicate the error. 

ERRORS 

enotdir A component of the path prefix isnot a directory. 

einval T he pathname contains a character with the high-order bit set. 

enametoolong A component of a pathname exceeded maxnamlen characters, or an enti re path 

nameexceeded maxpathlen characters. 

enoent Thenamedfiledoesnotexist. 

eacces Search permission isdenied for a component of the path prefix. 

eloop Too many symbolic linkswereencountered in translating the pathname. 

eio Anl/O error occurredwhile reading from thefilesystem. 



regcomp, regexec, regerror, regfree 
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SEEALSO 

readlink(2), getcwd(3) 

GNU, 29 J uly 1994 



Re_comp, re_exec 

re_comp, re_exec — BSD regex functions 

SYNOPSIS 

#include <regex.h> 

char *re comp(char *r e g e x ) ; 

int re exec(char *st r i ng ) ; 

D ESC RIPTIO N 

regcomp isused to compilethe null-terminated regularexpression pointed to Py regex. Thecompiled pattern occupies a static 
area, the pattern buffer, which isoverwritten by subsequent use of re_comp. If regex ìsnull, no operation is performed and 
the pattern Puffer's contents are not altered. 

re_exec isused to assess whether the null-terminated stri ng pointed to by stri ng matchesthepreviously compi led regex. 
RETURN VALUE 

regcomp returnsNULL on successful compilation of regex; otherwise, it returns a pointer to an appropriate errar message. 
re_exec returnsi for a successful match, zero forfailure. 

CONFO RMSTO 

BSD 4.3 

SEEALSO 

regex(7), GNU regex manual 

Linux, 14 J uly 1995 



regcomp, regexec, regerror, regfree 

regcomp, regexec, regerror, regfree — POSIX regex functions 

SYNOPSIS 

#include <regex.h> 

int regcomp) regex_t *preg, const char *r e g e x , int cflags); 

int regexec(const regex_t *preg, const char *string, size_t limateli, regmatch_t p ma t c h [ ] , int eflags); 
size_t regerror(int errcode, const regex_t * p r e g , char *errbuf, size_t er r buf _s i z e ) ; 
void regf ree(regex_t *preg); 



POSIX REGEX COMPI LING 

regcomp isused to compilea regular expression into aform that issuitable for subsequent regexec searches. 

regcomp issupplied with p r e g , a pointer to a pattern buffer Storage area; regex, a pointer to the null-terminated stri ng; and 
cf i ags, flagsused to determi ne the typeof compilation. Ali regular expression searching must Pedoneviaacompiled pattern 
Puffer; thus, regexec must alwaysPe supplì ed with theaddressof a regcomp initialized pattern buffer. 
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cf i ags may bethebitwiseor of oneor more of the following: 

reg_extended UsePOSIX extended regular expressi on syntaxwhen i nterpreti ng r eg ex . If 

not set, PO SIX basic regular expression syntax is used. 
reg_icase Do not differentiate case. Subsequent regexec searchesusingthispattern 

buffer wi II be case- in sensi ti ve. 
reg_nosub Support for substri ng addressing of matches is not required. The nmat eh and 

p ma t c h parametersto regexec areignored if the pattern buffer supplied was 

compiled with thisflagset. 

reg_newline M atch-any-character operatorsdon't match a newline A nonmatching list 

([-...]) not contai ni ng a newline matches a newline. M atch-beginning-of- 
lineoperator (-) matches the empty stri ng immediately after a newline, 
regardless of whether e f i ags, the executi on f lags of regexec, contai ns 
reg_notbol. M atch-end-of-l i ne operator ($) matches the empty stri ng 
immediately beforea newline, regardless of whether ef i a gs contains 

REGNOTEOL. 

PO SIX REGEX MATCHING 

regexec is used to match a null-terminated stri ng against the precompiled pattern buffer, preg. nmatch andpmatch are used to 
provide informati on regarding the location of any matches. ef i ags may bethebitwiseor of oneor both of reg_notbol and 
reg_noteol, whi eh cause changes i n matchi ng behavior descri bed in thefollowing list. 

reg_notbol T he match-begi nni ng-of-li ne operator always fai Is to match (butseethe 

compilation flag reg_newline, in the precedi ng subsection). Thisflag may beused 
when different porti onsof a stringare passed to regexec and thebeginningof the 
stri ng should not be i nterpreted as the begi nni ng of the li ne. 

reg_noteol T he match-end-of-l i ne operator always fai Is to match (but see the compilation 

flag reg_newline, in the precedi ng subsection). 

BYTE 0 FFSETS 

U nless regnosub was set for the compilation of the pattern buffer, it is possi bleto obtain substri ng match addressing 
information. p match must bedimensioned to haveat least nmatch elements. Thesearefilled in by regexec with substri ng 
match addresses. Any unused structure elements wi II contai n thevalue -1. 

Theregmatch_t structurethat isthetypeof pmatch is defi ned in regex.h: 

typedef struct 

regoff_t rm_so; 
regoff_t rm_eo; 
} regmatch_t; 



Each ™_so elementthat is not - 1 indicates the start offset of the next largest substri ng match within the stri ng. The relative 
™_eo element indicates the end offset of the match. 

PO SI X ERRO R REPO RTI N G 

regerror isused to tum the error codes that can bereturned by both regeomp and regexec into errar message stringa 

regerror ispassed theerror code, err code; the pattern buffer, preg; a pointer to a eh aracter stri ng buffer, err b u f ; and thesize 
of the stri ng buffer, errhuf _si ze. It returns the size of theer r buf required to contai n the null-terminated error messagestring. 
If both e r r b u f and e r r buf _ s i z e are non-zero, er r buf isfilled in with thefirst errbut_size - 1 charactersof theerror message 
and a terminati ng nuli. 



rem ove 



PO SIX PATTERN BUFFER FREEING 

Supplying regfree with aprecompiled pattern buffer, p r e g wi 1 1 freethememory allocateci to the pattern buffer by the 

COmpiling process, regcomp. 

RETURN VALUE 

regcomp returnszero for a successful compilation oran errar code for fai Iure, 
regexec returnszero for a successful match or regnomatch forfailure 



ERRORS 

Thefollowingerrorscan bereturned by regcomp: 



REGBADRPT 

REG_BADBR 

REG_EBRACE 

REGEBRACK 

REG_ERANGE 

REG_ECTYPE 

REG_EPAREN 

REGESUBREG 

REG_EEND 

REG_ESCAPE 

REG_BADPAT 

REG_ESIZE 

REG_ESPACE 

C0NF0RMST0 

POSIX 

SEEALSO 

regex(7), GNU regex manual 



Invalid useof repetition operators, such asusing* as the first eh aracter 
Invalid useof back referenceoperator 
U nmatched brace interval operators 
U nmatched bracket list operators 

Invalid useof the rangeoperator; for example, theending point of therange 

occurspriorto the starting point 

U nknown character class name 

U nmatched parenthesis group operators 

Invalid back referenceto asubexpression 

N on-specific error 

Invalid escape sequence 

Invalid useof pattern operators such as group or list 

Compiled regular expression requi res a pattern buffer larger than 64Kb 

The regex routines ran out of memory 



Linux, 13 July 1994 



remove 

remove— Deletes a name and possi bly the file to which it refers 
SYNOPSIS 

(finclude <stdio.h> 

int remove(const char ^pattinarne); 

DESCRIPTION 

remove deletesa namefrom thefilesystem. Ifthat name was the last link to a file and no processeshavethefileopen, the fi le 
isdeleted and the space it was usi ng is macie availablefor reuse. 

If the name was the last link to a file but any processes stili havethefileopen, the fi le wi II remain in existence until the last 
fi le descriptor referri ngto it isclosed. 
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If thenamereferred to asymbolic link, the link isramoved. 

If the name referred to asocket, fifo, or device, thenamefor it isremoved, but processesthat havetheobject open may 
conti nueto useit. 

RETURN VALUE 

On success, zero isreturned. On errar, -1 isreturned, and ermo issetappropriately. 
ERRORS 



E FAULT 
EACCES 



ENAMETOOLONG 
ENOENT 

ENOTDIR 

EISDIR 

ENOMEM 



EROFS 



p a t h n a me poi nts outsi de your accessi bl e address space. 
Write access to the directory contai ni ng pat hname isnot allowed forthe 
process'seffectiveuid, or oneof thedirectoriesin pat hname did not allow search 
(execute) permission. 

The directory contai ni ng pat hname has the sti cky-bit (s_isvtx) set and the 
process'seffectiveuid is neither the uid of the file to bedeleted northatof the 
directory containing it. 

pat hname wastOO long. 

A directory component in pat hname doesnot exist or isa dangling symbolic 
link. 

A component used as a directory in pat hname isnot, in fact, a directory. 

pat hname refersto a directory. 

I nsuffi ci ent kernel memory wasavailable. 

pat hname refers to a fi le on a read-only filesystem. 



C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

BUGS 

Inadequacies in the protocol underlying N FS can cause the unexpected disappearanceof filesthat are stili bei ng used. 
SEEALSO 

unlink(2), rename(2), open(2), rmdir(2), mknod(2), mkfifo(3), link(2), rm(l), unlink(8) 

Linux, 13 July 1994 



resjuery, res_search, res_mkquery, resjend, res_init, 
dn_comp,dn_expand 

res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand — Resolver routines 

SYNOPSIS 

#include <sys/types.h> 
#include <netinet/in.h> 
«include <arpa/nameser.h> 
«include <resolv.h> 

res_query(dname, class, t y p e , answer, anslen) 
const char *dname ; 
int c I as s , t y pe ; 
u_char *a ns wer ; 
int anslen: 



res query, rs_search, res_mkquery, res send, rsjnit, dn_comp, dn_expand 



res_search(dname, class, type, answer, ansi e n ) 
const char *d n a me ; 
int c I as s , type; 
u char *a ns wer ; 
int ans I en ; 



res mkquery(op, dname, class, type, data, datai e n , newrr, b u f , bufi e n ) 
int op ; 

const char *dname ; 
int c I as s , type; 
const char *d a t a ; 
int dat a I en ; 
struct rrec *newr r ; 
u_char *buf ; 
int bufi e n ; 



res_send(msg, msglen, answer, anslen) 
const u_char *ms g ; 
int msgl en ; 
u_char *a ns wer ; 
int anslen; 



res_init ( ) 



dn_comp(exp_dn, comp_dn, ength, dnptrs, lastdnptr) 
const char *e x p _ d n ; 
u char *comp_dn ; 
int length; 

u_char **dnpt r s , **l ast dnpt r ; 



dn_expand(msg, eomorlg, compjn, expjn, length) 
const u_char *msg, *eomorig, *comp_dn; 
char *exp_dn ; 
int length; 
hstrerror(int err); 



DESCRIPTION 

Theseroutinesareused for making, sending and interpreti ng query and reply messageswith Internet domain nameservers. 

Global configuration and state informati on that isused by the resolver routinesis kept in thestructure_res. M ost of the 
values nave reasonabledefaults and can beignored. 0 ptions stored in res.options aredefined in resoiv.h and areas 
follows. 0 ptions are stored as a simple bit mask containingthebitwiseor of the options enabled. 

res_init Trueif theinitial nameserver addressand default domain nameare 

initialized (that is, res_init has been called). 
res_debug P ri nt debuggi ng messages. 

res_aaonly Accept authoritati ve answers only. W ith this option, res_send should 

continueuntil itfindsan authoritative answer or fi ndsan error. 

Currently, thisisnot implemented. 
res_usevc UseTCP connectionsforqueries instead of UDP datagrams. 

res_stayopen U sed with res_usevc to keep theTC P connection open between queries. 

Thisisuseful only in programsthat regularly do many queries. UDP 

should bethenormal modeused. 
res_igntc Unused currently (ignoretruncation errors— don't retry with TCP). 

res_recurse Settherecursion-desired bit in queries. This is the default. (res_send does 

notdo iterative queries and expects the nameserver to handlerecursion.) 
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RES_NOALIASES 



RES DEFNAMES 



RESDNSRCH 



If set, res_search will append the default domain nameto single- 
component names (thosethat do not contain a dot). Thisoption is 
enabled by default. 

If thisoption is set, res_search will search for hostnames in thecurrent 
domain and in parent domai ns; seehostname(7). Thisisused by the 
standard host lookup routine gethostbyname(3). Thisoption isenabled 
by default. 

Thisoption turns off the user level aliasing feature controlied bythe 
hostaliases environment variable. N etwork daemonsshould set this 
opti on. 



Theres_init routine reads the configurati on fi le (if any; seeresoiver(5)) to get the default domain name, search list and the 
Internet addressof the locai n am e server! s). If no server isconfigured, the host runni ng the resolver istried. Thecurrent 
domain nameisdefined by thehostnameif notspecified in theconfiguration file; itcan beoverridden bythe environment 
variable localdomain. T hi smvironment variable may contai n several blank-separated tokens if you wish to overridethe 
search list on a per-process basi s. This issimilarto the search command in theconfiguration file. Another environment 
variable (res_options) can beset to overridecertain internai resolver options that areotherwiseset by changing fields i n the 
_res structure or are i nherited from theconfiguration file's options command. The syntax of the resoptions environment 
variable isexplai ned in resoiver(5). I n iti al i zati on normally occurson the first cali to oneof theother resolver routines. 

Theres_query function providesan interface to the server query mechanism. Itconstructsaquery, sendsitto thelocal 
server, awaitsa response, and makespreliminarychecksonthereply.Thequery requestsinformation of the specified type 
and class for the speci fi ed fully-qualified domain name dna me. Thereply messageisleft in theanswer buffer with length 
ansi en supplied by thecaller. 

Theres_search routi ne makes a query and awaitsa response likeres_query, but in addition, it implements the default and 
search rules controlied by the res_defnames and resjnsrch options. It returns the first successful reply. 

The remai ni ng routines are lower-level routi nesused by res_query. The resjnkquery function constructs a standard query 
messageand places it in but. It returns the sizeof the query, or -1 if the query is largerthan bufien. The query type op is 
usually query, but can beanyof the query typesdefi ned in <arpa/nameser.h>. The domain name for the query isgiven by 
d n a me . Newm is currently unused but isintended for making update messages. 

Theres_send routine sends a preformatted query and returns an answer. It will cali resimt if res_init is not set, send the 
query to thelocal name server, and handletime-outsand retri es. The length of thereply messageis return ed, or-1 if there 
were errors 

T he dn_comp function compresses the domain nameexp_dn and storsi t in conip_dn.T he sizeof the compressed nameis 
returned or -1 if there were errors. The sizeof the array pointed to by comp_dn isgiven by length. Thecompression usesan 
array of pointersdnptrs to previously-compressed names in thecurrent message. The first pointer pointsto thebeginningof 
the messageand the list endswith null. The limi tto the array is specified by ìastdnptr. A side effect of dn^comp isto update 
the list of pointersfor labels inserted into the message as the nameis compressed. If dnptr ìsnull, names are not compressed. 
If ìastdnptr ìsnull, thelist of labels is not updated. 

Thedn_expand entry expands the compressed domain namecomp_dn to a full domain name. The compressed nameis 
contained in a query or reply message; msg is a pointer to thebeginning of the message. The uncompressed nameisplaced in 
the buffer indicated by exp_dn, which isof sizeiength. The sizeof compressed nameis returned or-1 if there wasan errar. 



FILES 



/etc/resolv.conf 



See resolver(5) 




SEEALSO 

gettiostbyname(3), named(8), resolver(5), hostname(7), 
RFC1032, RFC1033, RFC1034, RFC1035, RFC974 
SM M : 11 N ame Server 0 perations Guide for BIN D 

11 Decemberl995 

rewinddir 

rewinddir— Resets directory stream 
SYNOPSIS 

#include <sys/types.h> 
#include <dirent.h> 
void rewinddir(DIR *dir); 

DESCRIVO N 

The rewinddir) ) function resets the positi on of the directory stream dir to thebeginning of the directory. 

RETURN VALUE 

Thereaddiro function returns no value. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEEALSO 

opendir(3), readdir(3), closedir(3), seekdir(3), telldir(3), scandir(3) 

11 Junel995 

rint 

rint— Roundsto closest integer 
SYNOPSIS 

#include <math.h> 
doublé rint (doublé x); 

DESCRIPTION 

The rinto function roundsx toan integer value accordingto the prevalent rounding mode. The default rounding modeis 
to round to thenearest integer. 

RETURN VALUE 

The rinto function returns the integer value asafloating-point number. 
C0NF0RMST0 

BSD 4.3 
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SEEALSO 

abs(3), ceil(3), fabs(3), floor(3), labs(3) 

6 Junel993 

rquota 

rquota— Implementsquotason remote mach ines 
SYNOPSIS 

/ usr/ include/ rpcsvc/ rquota .x 

DESCRIVO N 

Therquotai ) protocol inquires about quotason remote mach ines. Itisused in conjunction with N FS because N FS itself 
does not implement quotas. 

PROGRAMMINO 

#include <rpcsvc/rquota. h> 

ThefollowingXDR routines are avai lable in ìibrpcsvc: xdr_getquota_arg: 

xdr_getquota_rslt 
xdr_rquota 

SEEALSO 

quota(l), quotactl(2) 

6 October 1987 

scandir, alphasort 

scandir, alphasort— Scan a directory for matching entries 
SYNOPSIS 

(finclude <dirent.h> 

int scandir(const char *dir, struct dirent ***namel i st , 
int (*sel ect ) (const struct dirent *), 

int ( *c o mp a r ) (const struct dirent **, const struct dirent **)); 
int alphasort(const struct dirent **a , const struct dirent **b); 

DESCRIPTION 

The scandirò function scans the directory di r , calling seiecto on each directory entry. Entries for which seiecto returns 
non-zero arestored in strings allocateci viamaiioco, sorted usingqsorto with thecomparison function comparo, and 
collected in array n a me i st that isallocated viamaiioco.lf seiect ìsnull, ali entries are selected. 

The alphasort o function can beused as thecomparison function for the scandirò function to sort the directory entries into 
alphabetical order. Its parameters arethetwo directory entries, a and b, to compare. 

RETURN VALUE 

The scandirò function returnsthenumberof directory entries selected or -1 if an errar occurs. 

The alphasort o function returns an integer lessthan, equal to, or greater than zero if the first argument isconsidered to be 
respectively lessthan, equal to, or greater than thesecond. 



sanf, fscanf, sscanf, vscanf, vsscanf, vfscanf 



ERRO RS 

enomem Insufficient memory to complete the operation 

CONFO RMSTO 

BSD 4.3 

EXAMPLE 

/* print files in current directory in reverse order */ 
#include <dirent.h> 
main( ){ 

struct dirent "narnel i st ; 

int n ; 

n = scandir) " . " , &n a me I i st , 0, al phasort ); 
if (n < 0) 

perror( "scandir" ) ; 

else 

while(n— ) printf ( "%s\n" , n a me I i s t [ n ] - >d _ n a me ) ; 

} 

SEEALSO 

opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), seekdir(3) 

GNU, 11 Aprii 1996 



scanf , fscanf, sscanf, vscanf , vsscanf, vfscanf 

scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf— Input format COnversion 

SYNOPSIS 

#include <stdio.h> 

int scanf ( const char 'format, ...)] 

int fscanf ( FILE *st r eam, const char *f or mat , . . . ) ; 

int sscanf ( const char *str, const char *format, ...); 

#include <stdarg.h> 

int vscanf ( const char *f or mat .valist ap); 

int vsscanf) const char *str, const char *f o r mat , va_ist ap); 

int vfscanff FILE *stream, const char *f or mat ,va_list ap); 



DESCRIPTION 

The scanf family of functions scansi nput accordi ngto a format asdescribed bel ow. This format may contai n conversion 
specifiers; theresultsfrom such conversi ons, if any, arestored through the pointer arguments. The scanf function reads 
input from thestandard input stream stdin, fscanf reads input from thestream pointer stream, and sscanf reads its input 
from thecharacter stri ng pointed to by st r . 

The vfscanf function isanalogousto vf printf (3) and reads input from thestream pointer stream using a variableargument 
list of pointers(seestdarg(3)). The vscanf function scansa variableargument list from thestandard input and the vsscanf 
function scans it from a string; theseareanalogousto thevprintf and vsprintf functions respectively. 

Each successive pointer argument must correspond properly with each successive conversion specifier. Ali conversi ons are 
introduced by the% (percent sign) character. The format string may also contai n other characters. Whitespace(such as 
blanks, tabs, or newlines) in the format string match any amount of whitespace, includi ng none, in the input. E veryth ingelse 
matchesonly itself. Scanni ngstopswhen an input character doesnot match such a format character. Scanning also stops 
when an input conversion cannot be made. 
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CONVERSIONS 

Following the% character introduci ng a conversi on, theremay beanumber of flag characters, asfollows: 

Suppresses assi gnment. The conversion thatfollowsoccursas usuai, but no pointer isused; theresult of 

theconversion issimply discarded. 
a Indicatesthat the conversion will bes, maiioc wi II beapplied to theneeded memory space for the stri ng, 

and thepointerto it will beassigned to thechar pointer variable, which doesnot haveto beinitialized 

before. T hisflag does not exist in AN SI C. 
h Indicatesthat the conversion will beone of dioux or n and thenext pointer is a pointer to a short int 

(ratherthan int). 

1 Indicates either that theconversion will beone of dioux or n and thenext pointer isa pointer to a long 
int (ratherthan int), or that theconversion will beone of etg and thenext pointer isa pointer to 
doublé (ratherthan tioat). Specifyingtwo 1 flags isequivalentto the l flag. 

l Indicates that the conversion will be either etg and thenext pointer isa pointer to long doublé or the 
conversion will bedioux and thenext pointer isa pointer to long long. (N ote that long long isnot an 
AN SI C type. Any program using thiswill not beportableto ali architectures). 

q Equivalentto l.T hisflag does not exist in ANSI C. 

In addition to these flags, there may bean optional maximum field width, expressed asa decimai integer, between the% and 
theconversion. If no width isgiven, a default of intinity isused (with oneexception, below); otherwise, at mostthismany 
characters are scanned in processing the conversion. Before conversion begins, mostconversions skip whitespace; this 
whitespace is not counted against thefield width. 

T he followi ng conversi ons are avai lable: 

% M atches a I iterai %. That is, %% in the format stri ng matches a si ngle input % character. N o conversion is 

done, and assi gnment does not occur. 
d M atches an optional ly signed decimai integer; thenext pointer must bea pointer to int. 

d Equivalentto id; thisexi stsonly for backwardscompatibility. 

i M atches an optional ly signed integer; thenext pointer must bea pointer to int. The integer is read in 

base 16 if it begins with ex or ex, in base 8 if it begins with e, and in base 10 otherwise. 0 nly 
characters that correspond to the base are used. 

o M atches an unsigned octal integer; thenext pointer must bea pointer to unsigned int. 

u M atches an unsigned decimai integer; thenext pointer must bea pointer to unsigned int. 

x M atches an unsigned hexadecimal integer; thenext pointer must bea pointer to unsigned int. 

x Equivalentto x. 

t M atches an optional ly signed floati ng-point number; thenext pointer must bea pointer to float. 

e Equivalentto t. 

g Equivalentto f. 

e Equivalentto t. 

s M atches a sequenceof nonwhitespace characters; thenext pointer must bea pointer to char, and the 

array must belargeenough to accept ali thesequenceand the termi nati ng NU L character. The input 
stri ng stopsat whitespace or at the maximum field width, whichever occurs first. 

c M atches a sequenceof width count characters (default 1); thenext pointer must bea pointer to char, 

and there must beenough room for ali the characters (no termi nati ngNui isadded). The usuai skip of 
leading whitespace issuppressed. To skip whitespace first, use an explicit space in theformat. 

[ M atchesa nonempty sequenceof characters from thespecified set of accepted characters; thenext 

pointer must bea pointer to char, and there must beenough room for ali the characters in the stri ng, 
plus a termi nating nul character. The usuai skip of leading whitespace issuppressed. The stri ng isto be 
madeup of characters in (or not in) a parti cular set; the set is defined by the characters between the 
open bracket [ character and aclosebracket ] character. The set excludesthose characters if the first 



seekdir 




character after the open bracket isacircumflex(-).To include a dose bracket in the set, makeitthe 
first eh aracter after the open bracket or the ci rcumflex; any other position will end the set. Thehyphen 
character (-) i salso special; when placed between two other characters, it addsall intervening 
charactersto theset.To includea hyphen, make it the last character before the final dose bracket. For 
instance, ["]a-9] meansthe set "everythingexcept dose bracket, zero through nine, and hyphen." 
The stri ng endswith the appearanceof a character notin (or, with a ci rcumflex, in) the set or when 
thefield width runsout. 

p M atches a pointer value (aspri nted by %p in printf(3); thenext pointer must bea pointer to void. 

n N othing isexpected; instead, thenumber of characters consumed thusfar from the input isstored 

through thenext pointer, which must bea pointer to mt. Thisisnot aconversion, although it can be 

suppressed with the* flag. 

RETURN VALUES 

Thesefunctions return thenumber of input items assigned, which can befewer than provided for, or even zero, in theevent 
of a matching fai Iure. Zero indicatesthat, whi le therewas input available, no conversi onswere assigned; typically, this isdue 
to an invalid input character, such asan alphabetic character for a %d conversion. The value eof isreturned if an input fai Iure 
occurs before any conversi on such asan end-of-fileoccurs. If an errar or end-of-fileoccurs after conversion hasbegun, the 
number of conversions which were successfully completed is returned. 

SEE ALSO 

strtol(3), strtoul(3), strtod(3), getc(3), printf(3) 

STANDARD S 

Thefunctionstscanf, scanf, and sscanf conform to AN SI C3. 159-1989 (AN SI C). 

Theq flag isthe BSD 4.4 notati on for long long, whileu ortheusageof l in integer conversions istheGN U notation. 

The Linux versi on of thesefunctions is based on theGN U iìòìo library. Takea look at the info documentation of GN U 
ubo (gli bc-1.08) for a more concise descri ption. 

BUGS 

Ali functions are fully AN SI C3.159-1989-conformant, but provide the additional flagsq and a aswell asan additional 
behavior of theL and 1 flags. T he latter may beconsidered to bea bug, asit changes the behavior of flags defined in AN SI 
C 3.159-1989. 

Somecombinationsof flags defined byANSI C arenotmakingsensein ANSI C (forexample, %i_d). W hilethey may havea 
well-defined behavior on Linux, thisneed notto beso on other archi tectu res. Theref ore, it usuai ly isbetter to use flags that 
arenot defined by AN SI C at ali, that is, useq instead of l in combination with diouxx conversions or n. 

Theusageof q isnot thesameason BSD 4.4, asit may beused in float conversions equi valently to l. 

Linux man page 1 N ovember 1995 

seekdir 

seekdir— Sets the position of the next readdir) ) cali in the directory stream. 
SYNOPSIS 

#include <dirent.h> 

void seekdir(DIR *di r ,off_t offset ); 

DESCRI PTION 

Theseekdiro function sets the location in the directory stream from which thenext readdiro cali will start, seekdiro 
should beused with an offset returned by teiidiro. 
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RETURN VALUE 

Theseekdiro function returns no valua 

CONFO RMSTO 

BSD 4.3 

SEEALSO 

lseek(2), opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), scandir(3) 

31 M arch 1993 

setbuf, setbuff er, setlinebuf, setvbuf 

setbuf, setbuffer, setlinebuf, setvbuf — Stream buffering operations 
SYNOPSIS 

#include <stdio.h> 

int setbuf( FILE *s t r e a m , char *buf); 

int setbuffer( FILE *stream, char * b u f , sizejsize); 

int setlinebuf( FILE *s t r e a m) ; 

int setvbuf) FILE *stream, char *buf, i nt mode , size_t size); 

DESCRIPTION 

Thethreetypesof buffering availableareunbuffered, block buffered, and line buffered. When an output stream isunbuf- 
fered, informati on appearson the desti nati on file or terminal assoon aswritten; when it is block buffered, many characters 
aresaved up and written as a block; when it is line buffered, characters are saved up until a newl i ne is output or input isread 
from any stream attached to a terminal device(typically stdin). Thefunction ffiush(3) may beused to force the block out 
early. (Seefciose(3).) N ormally ali fi les are block buffered. W hen the first I/O operation occurson a file, maiioc(3) iscalled, 
and a buffer isobtained. If a stream refersto a terminal (asstdout normally does), it is line buffered. The standard errar 
stream stderr isalwaysunbuffered. 

The setvbuf function may beused at any ti me on any open stream to changeits buffer. The mode parameter must beone of 
thefollowingthreemacros: 

_ionbf Un buffered 

_iolbf Line buffered 

_iofbf Fui ly buffered 

Except for unbuffered fi les, the buf argument should pointto a buffer at least si ze byteslong; this buffer wi II beused instead 
of thecurrent buffer. If the argument buf ìsnull, only the mode isaffected; anew buffer wi II be allocateti on thenext read or 
write operation. The setvbuf function may beused at any ti me, but can only change the mode of a stream when it isnot 
"active"; that is, beforeany I/O, or immediately after a cali to ffiush. 

T he other three callsare, in effect, simply aliases for Calisto setvbuf. The setbuf function isexactly equivalentto the cali: 

setvbuf (s t r ea m, buf, buf ?_IOFBF :_IONBF, BUFSIZ); 

The setbuffer function isthesame, except that the size of the buffer isup to the Caller, rather than being determi ned by the 
default bufsiz. The setlinebuf function isexactly equivalent to the cali: 

setvbuf(stream, (char *)NULL,_IOLBF, 0); 



setenv 




SEEALSO 

fopen(3), fclose(3), fread(3), malloc(3), puts(3), printf(3) 

STANDARD S 

Thesetbuf and setvbuf functionsconformtoANSI C 3.159-1989 (ANSI C). 
BUGS 

Thesetbuffer and setiinebuf functions are not portableto versionsof BSD before4.2BSD, and may not beavailable under 
Linux. On 4.2BSD and4.3BSD systems, setbuf alwaysusesa suboptimal buffer si ze and should beavoided. You must make 
surethat both buf and the space it pointsto stili exist by thetimestream isclosed, which also happensat program termi na- 
tion. For example, thefollowing is illegali 

#include <stdio.h> 

int main() 

{ 

cbar buf[BUFSIZ]; 
setbuf (stdin, buf ) ; 
printf ( "Hello, world!\n"); 
return 0; 

} 

BSD man page, 29 N ovember 1993 

setenv 

setenv— C hanges or adds an envi ronment vari able 
SYNOPSIS 

#include <stdlib.b> 

int setenv(const char *name, const cbar *value,int overwrite); 
void unsetenv(const char *name); 

D ESC RIPTIO N 

The setenv o function adds the vari able nameto the envi ronment with thevaluevaiue, if n a me does not al ready exist. If na me 
does exist in the envi ronment, then itsvalueischanged to vaiue if overwrite is non-zero; if overwrite is zero, then thevalue 
ofname is not changed. 

Theunsetenvo function deletesthevariablename from the envi ronment. 
RETURN VALUE 

Thesetenvo function returnszero on success, or -1 if therewasinsufficient space in the envi ronment. 
C0NF0RMST0 

BSD 4.3 

SEEALSO 

getenv(3), putenv(3) 

BSD, 4 Aprii 1993 
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set jmp 

setjmp— Savesstack contextfor nonlocal goto 
SYNOPSIS 

#include <setjmp.h> 

int setjmp( jmp_buf env ); 

D ESC RIPTIO N 

setjmp and iongjmp(3) areuseful for dealingwith errorsand interruptsencountered in a low-level subroutineof a program, 
setjmpo savesthestack contextyenvironment in env for later use by long jmpo. The stack contextwill beinvalidated if the 
function which called setjmpo returns. 

RETURN VALUE 

It returns the valuea if returni ng di rectly and non-zero when returni ngfrom ìongjmpo using thesaved context. 
C0NF0RMST0 

POSIX 

NOTES 

POSIX doesnotspecify if the si gnal contextwill besaved ornot. If you wantto savesignal masks, usesigsetjmp(3). setjmpo 
makesprogramshard to understand and maintain. If possi ble, an alternative should beused. 

SEEALSO 

longjmp(3), sigset jmp(2), siglong j mp{2 ) 

25 N ovember 1994 



setlocale 

setiocaie— Sets the current locale 
SYNOPSIS 

#include <locale.h> 

char *setlocale(int category, const char * locale); 

DESCRIPTION 

The setiocaie o function isused to set or query the program's current locale. If i oc ai e isC or POSIX, the current locale is 
setto the portable locale. 

If i oc ai e is "", the locale is set to the default locale that i s sei ected from the environment vari ablei_ANG. 
On startup of themain program, theportable localeisselected as default. 
Theargumentcategory determines which functions are influenced by thenew locale: 
lc_all Forali of the locale 

LC_COLLATE For the functions st rcoll ( ) and strxfrmO. 

lc_ctype Forthecharacter classification and conversion routines. 

LC_MONETARY For localeconv ( ) . 

lcjumeric For the decimai character. 

lc_time For strftimeo. null if the request can not behonored. Thisstring may be 

allocateci in stati c Storage. 



si gemptyset, si gf i 1 1 set, sigaddsst, sigdelset, sigismember 




A program may bemadeportableto ali locale by callingsetiocaie(Lc_ALL, ) after program i ni ti al izati on, by using the 

vai ues return ed from aiocaieconvo cali for locale- dependent informati on and by using strcoiio or strxfrmo to compare 
strings. 

C0NF0RMST0 

ANSI C, POSIX.l 

Linux supports the portable locales C and POSIX and also theEuropean Lati n-1 and Russi an locales. 
Theprintf o family of functionsmay or may not honorthecurrent locale. 

SEE ALSO 

locale(l), localedef (1), strcoll(3), ìsalpha(3), localeconv(3), strftime(3), locale(7) 

GNU, 18 Apri 1 1993 

siginterrupt 

siginterrupt— Allowssignalsto interrupt system calls 
SYNOPSIS 

#include <signal.h> 

int siginterrupt (int sig, int flag); 

DESCRIPTION 

The siginterrupto function changes the restart behavior when a system cali is interrupted by the signal sig.lf the f lag 
argument is false (a), then systems calls wi II berestarted if interrupted by thespecified signal sig. Thisis the default behavior 
in Linux. H owever, when anew signal handler isspecified with thesignai(2) function, the system cali is interrupted by 
default. 

If the tiag argument istrue(i) and no data hasbeen transferred, then a system cali interrupted by the signal sig wi 1 1 return 
-1 andtheglobal variableer r no will be setto eintr. 

If the fiag argument istrue {1 ) and data transfer hasstarted, then the system cali will be interrupted and will return the 
actual amount of data transferred. 

RETURN VALUE 

The siginterrupto function returnso on success, or -1 if the signal number sig isinvalid. 
ERRORS 

einval Thespecified signal number isinvalid. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

signal(2) 

13 Aprii 1993 



sigemptyset, sigf illset, sigaddset, sigdelset, sigismember 

sigemptyset, sigf illset, sigaddset, sigdelset, sigismember— PO SIX Signal Set Operations 
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SYNOPSIS 

#include <signal.h> 

int sigemptyset (sigset_t *set); 

int sigfillset(sigset_t *set); 

int sigaddset (sigset_t *s et , int si g n u m ) ; 

int sigdelset(sigset_t *s et , int signum); 

int sigismember(const sigsetjt *set,int signum); 

DESCRIPTION 

Thesigsetops(3) functionsallow the manipulation of POSIX signal sets 

sigemptyset i nitializes the signal set given by set to empty, with ali signals excluded from the set. 

sigfiiiset initializesset to full, i ncludi ng al I signals. 

sigaddset and sigdeiset add and delete, respectively, signal signum from set . 

sigismember tests whether si g n u m i s a member of set . 

RETURN VALUES 

sigemptyset, sigtuiiset, sigaddset, and sigdeiset return 0 on successand -1 on errar, 
sigismember returnsi if signum is a member of set, 0 if signum is not a member, and -1 on error. 

ERRORS 

einval si g isnot a valid signal. 

CONFO RMSTO 

POSIX 

SEEALSO 

sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2) 

Linux 1.0, 24 September 1994 



sin 

sin— Sinefunction 
SYNOPSIS 

#include <math.h> 
doublé sin(double x ) ; 

DESCRIPTION 

The sino function returnsthesineof x, wherex is given in radians. 

RETURN VALUE 

The sino function returnsavaluebetween -1 and 1. 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 



sleep 



SEEALSO 

acos(3), asin(3), atan(3), atan2(3), cos(3), tan(3) 

8 Junel993 



sinh 

sinh— H yperbolic sine function 
SYNOPSIS 

#include <math.h> 
doublé sinh(double x ) ; 

DESCRIPTION 

T he sinh o function returns the hyperbolic sineof x, which is defi ned mathematically as[exp(x)-exp(-x)] / 2. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acosh(3), asinh(3), atanh(3), cosh(3), tanh(3) 

13 Junel993 

sleep 

sieep— Sleeps for the specified number of seconds 
SYNOPSIS 

#include <unistd.h> 

unsigned int sleep(unsigned int seconds); 

DESCRIPTION 

sieepo makesthecurrent process sleep unti I seconds seconds haveelapsed or a signal arrivesthat isnot ignored. 
RETURN VALUE 

Theretum valueiszero if the requested timehaselapsed, orthenumber of seconds left to sleep. 
CONFO RMSTO 

POSIX. 1 

BUGS 

sieepomay beimplemented usi ng sigalrm; mixing Calisto alarmi ) and sieepo isa bad idea. 

Using ìongjmpo from a signal handleror modifying the handlingof sigalrm whi le sleepingwi II cause undefi ned results. 

SEEALSO 

signal(2), alarm(2) 

GNU, 7 Aprii 1993 
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snprintf, vsnprintf 

snprintf , vsnprintf— Formattai output conversion 
SYNOPSIS 

#include <stdio.h> 

int snprintf ( char *str, size_t n, 
const char *f or ma t , ... ) ; 

#include <stdarg.h> 

int vsnprintf ( char *str, size_t n, 
const char *format, va_list ap ); 

D ESC RIPTIO N 

snprintf writes output to the stri ngst r, under control of the f ormat stri ng that specifies how subsequent argumentsare 
converted for output. It issimilarto sprintf(3), exceptthat n specifies the maximum number of characters to produce. 
The trai li ng nuli character iscounted towardsthis limit, so you should allocate at leastn characters for the stri ngst r . 

vsnprintf is the equi vai ent of snprintf with thevariableargument list specified directly asfor vprintf. 
RETURN VALUE 

The return valueis the number of characters stored, not includi ng the termi nati ng nuli. If this value equalsn, then therewas 
not enough space in str forali the output. You should try again with a bigger output stri ng. 

EXAMPLE 

H ere is a sample program that dynamically enlarges its output buffer: 

/* Construct a message describing the value of a 

variable whose name is NAME and whose value is 

VALUE . */ 
char * 

makejnessage (char *name, char *value) 
{ 

/* Guess we need no more than 100 chars of space. */ 
int size = 100; 

char "buffer = (char *) xmalloc (size); 
while (1) 
{ 

/* Try to print in the allocated space. */ 
int nchars = snprintf (buffer, size, 

"value of %s is %s", name, value); 
/* If that worked, return the string. */ 
if (nchars < size) 

return buffer; 
/* Else try again with twice as much space. */ 
size *= 2; 

buffer = (char *) xrealloc (size, buffer); 

} 

} 

C0NF0RMST0 

TheseareGNU extensions. 



stdarg 
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SEEALSO 

printf(3), sprintf (3), vsprintf (3), stdarg(3) 

GNU, 16 September 1995 



sqrt 

sqrt— Square root function 
SYNOPSIS 

#include <math.h> 
doublé sqrtfdouble x ) ; 

DESCRIPTION 

Thesqrto function returns the non-negative square root of x. 1 1 fai Is and setsermo to edom, if x isnegative. 
ERRO RS 

edom x isnegative. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

hypot(3) 

21 junel993 



stdarg 

stdarg— Vari ableargument liste 
SYNOPSIS 

#include <stdarg.h> 
void va_start( va_list ap, last); 
type va_arg( va_list ap, type); 
void va_end( vaJList ap); 

DESCRIPTION 

A function may becalled with a varying number of argumentsof varyingtypes. The include fi le stdarg. h declaresatype 
va_iist and definesthree macrosfor stepping through a list of argumentswhose number and typesarenot known to the 
called function. 

Thecalled function must declarean object of type va_nst that isused by themacrosva_start, va_arg, and va_end. 

Theva_start macro i n iti al izes a p forsubsequent useby va_arg and va_end, and must becalled first. 

Theparameter a s t is the nameof the last parameter before the vari ableargument list; that is, the last parameter of which 
the calling function knows the type. 

Because the addressof this parameter isused in theva_start macro, it should not bedeclared asa register variable, a 
function, oran arraytype 

Theva_start macro returns no value. 
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Theva_arg macro expandsto an expression that hasthetypeand valueof thenext argument in the cali. Theparameter ap is 
thevajist ap initialized by va_start. Each cali to va_arg modifiesap so that thenext cali returns thenext argument. The 
parameter typeisatypenamespecified so that the typeof a pointer to an object that hasthespecified typecan beobtained 
simply by adding a * to type. 

If thereisno next argument, or if type isnotcompatiblewith the typeof the actual next argument (as promoted according 
to the default argument promotions), random errorswill occur. 

The first useof theva_arg macro after that of theva_start macro returns the argument after last. Successive invocations 
return thevalues of the remai ni ng arguments. 

Theva_end macro handlesa normal return from thefunction whosevariable argument list was initialized by va_start. 
Theva_end macro returns no value 

EXAMPLE 

Thefunction too takesa string of format characters and printsout the argument associ ated with each format character based 
on the type 

void foo(char *fmt, . . . ) 

< 

va_list ap; 
int d; 

char c, *p, *s; 

va_start(ap, fmt); 
while (*fmt) 

switch(*fmt++) { 

case 's' : /* string */ 

s = va_arg(ap, char *) ; 
printf( " string %s\n" , s); 
break; 

case ' d ' : /* int */ 

d = va_arg(ap, int) ; 
printf ( "int %d\n" , d) ; 
break; 

case 'e' : /* char */ 

c = va_arg(ap, char) ; 
printf ( "char %c\n" , c) ; 
break; 

} 

va_end(ap) ; 

} 

STANDARD S 

Thevastart, va_arg, and va_end macros conform to AN SI C 3.159-1989 (ANSI C). 
COMPATIBILITY 

These macros are not compati ble with thehistoric macros they replace. A backwards-compatibleversion can befound in the 

includefilevarargs.h. 

BUGS 

U nlikethevarargs macros, thestdarg macros do not permit programmersto codeafunction with no fixed arguments This 
problem generateswork mainly when converti ngvarargs codeto stdarg code but it also createsdifficultiesfor variadic 
functions that wish to passali of their arguments on to afunction that takesa va_iist argument, such asvf printf (3). 

BSD man page, 29 N ovember 1993 
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stdio— Standard input/output library functions 
SYNOPSIS 

#include <stdio.h> 
FILE *stdin; 
FILE *stdout; 
FILE *stderr; 

D ESC RIPTIO N 

The standard I/O library providesasimpleand efficient buffered stream I/O interface. Input and output is mapped into 
logicai data streams and the physi cai I/O characteristics are concealed. The functions and macrosarelisted in thissection; 
moreinformation isavailablefrom theindividual man pages. 

A stream is associ ated with an external file (which may bea physical device) by openingafile, which may i nvolve creati ng a 
new file. C reati ngan exi sti ng file causes its former conteneste bediscarded. If afilecan support positioning requests(such as 
a disk file, asopposed to a terminal), then a file positi on indicator associateci with the stream ispositioned at the start of the 
fi le (byte zero), unlessthefileisopened with append mode. If append modeisused, the posi tion indicator wi II beplaced the 
end-of-file. The position indicator ismaintained by subsequent reads, writes, and positioning requests. Ali input occursasif 
thecharacterswereread by successive Calisto thetgetc(3) function; ali output takes place as if ali characterswereread by 
successive Calisto thetputc(3) function. 

A fi le is di sassoci ated from a stream by closing the fi le. Output streams are flush ed (any unwritten buffer contentsare 
transferred to thehost environment) befo re the stream is di sassoci ated from the file. Thevalueof a pointer to a file object is 
indeterminate after a file isclosed (garbage). 

A fi le may besubsequently reopened, by thesameoranother program execution, and itscontentsreclaimed or modified (if it 
can be reposi tion ed at the start). If themain function returnsto its originai Caller, ortheexit(3) function iscalled, ali open 
filesareclosed (hence ali output streams are flush ed) befo re program termi nati on. Other methodsof program termi nati on, 
such asabort(3) do not bother about closing files properly. 

At program startup, threetext streams are predefined and need not beopened explicitly: standard input (for reading 
conventi onal input), standard output (forwriting conventi onal input), and standard errar (for writing diagnostic output). 
These streams are abbreviated stdin, stdout, and stderr. W hen opened, the standard errar stream isnot fully buffered; the 
standard input and output streams are fully buffered if and only if the streams do notte referto an interactivedevice. 

Output streams that referto terminal devices are always li ne buffered by default; pendi ng output to such streams iswritten 
automatically whenever an input stream that refersto a terminal device is read. In cases where a largeamount of computation 
isdone after printing part of a li neon an output terminal, it isnecessary to ffiush(3) the standard output beforegoing off 
and computing so that the output will appear. 

The stdio library isa part of the library libo and routines are automatically loaded as needed by the compi lerscc(l) and 
pc(l). The synopsis sectionsof thefollowing manual pages indicate which include files areto beused, what the compi ler 
declaration for the function looks like, and which external vari ables are of interest. 

Thefollowing are defined asmacros; these names may not bereused without first removi ng their current definitions with 

#undef : BUFSIZ, EOF, FILENAME_MAX, FOPENJIAX, L_cuserid, L_ctermid, L_tmpnam, NULL, SEEK_END, SEEK_SET, SEE_CUR, TMPJIAX, 
clearerr, feof, ferror, fileno, fropen, fwopen, getc, getchar, pute, putehar, stderr, stdin, stdout. Function versions Of the 
macro functionSfeof, ferror, clearerr, fileno, getc, getchar, pute, and putehar exist and will beused if themacrOS 

defi nitions are explicitly removed. 
SEEALSO 



open(2), close(2), read(2), write(2) 
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BUGS 

The standard buffered functions do not i nteract well with certain other library and system functions, especi al ly vfork and 
abort. This may not be the case under Linux. 

STANDARD S 

T he stdio library conformsto ANSI C 3.159-1989 (ANSI C). 
LIST OF FUNCTIONS 



Function 


D escription 


clearerr 


C heck and reset stream status 


fclose 


Closeastream 


fdopen 


Stream open functions 


feof 


C heck and reset stream status 


f error 


C heck and reset stream status 


fflush 


Flush a stream 


fgetc 


G et next character or word from i nput stream 


fgetline 


Get a linefrom a stream 


fgetpos 


Reposi ti on a stream 


fgets 


Get a linefrom a stream 


fileno 


C heck and reset stream status 


fopen 


Stream open functions 


f printf 


Formatted output conversion 


fpurge 


Flush a stream 


fputc 


0 utput a character or word to a stream 


fputs 


Output a lineto a stream 


f read 


Binary stream input/output 


f reopen 


Stream open functions 


f ropen 


0 pen a stream 


fscanf 


Input format conversion 


fseek 


Reposi ti on a stream 


fsetpos 


Reposi ti on a stream 


ftell 


Reposi ti on a stream 


fwrite 


Binary stream input/output 


getc 


G et next character or word from i nput stream 


getchar 


G et next character or word from i nput stream 


gets 


Get a linefrom a stream 


getw 


G et next character or word from i nput stream 


mktemp 


M aketemporary filmarne (unique) 


perror 


System error messages 


printf 


Formatted output conversion 


putc 


0 utput a character or word to a stream 


putchar 


0 utput a character or word to a stream 


puts 


Output a lineto astream 


putw 


0 utput a character or word to a stream 



àpcpy 



remove 

rewind 

scanf 

setbuf 

setbuffer 

setlinebuf 

setvbuf 

sprintf 

sscanf 

strerror 

sys_errlist 

sysjierr 

tempnam 

tmpf ile 

tmpnam 

ungete 

vf printf 

vf scanf 

vprintf 

vscanf 

vsprintf 

vsscanf 



Rem ove directory entry 
Reposi ti on a stream 
Input f o rm at con versi on 
Stream buffering operati ons 
Stream buffering operations 
Stream buffering operations 
Stream buffering operations 
Formatted output conversion 
Input format conversion 
System error messages 
System error messages 
System error messages 
Temporary fileroutines 
Temporary fileroutines 
Temporary fileroutines 
U n-get character from input stream 
Formatted output conversion 
Input format conversion 
Formatted output conversion 
Input format conversion 
Formatted output conversion 
Input format conversion 
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stpcpy 

stpcpy— C opies a stri ng returning a pointer to its end 
SYNOPSIS 

#include <string.h> 

char *stpcpy(char *dest , const char *src); 

D ESC RIPTIO N 

Thestpcpyo function copiesthe string pointed to by sre (including theterminating \a character) to thearray pointed to by 
dest . The stri ngsmay not overlap, and the desti nati on string dest must belargeenough to receive the copy. 

RETURN VALUE 

stpcpy o returns a pointer to the end of the string dest (that is, theaddressof theterminating nuli character) rather than the 
beginning. 

EXAMPLE 

For example, this program uses stpcpy to concatenate too and bar to produce foobar, which it then prints: 

(finclude <string.h> 



int 

main (void) 
{ 
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char *to = buffer; 
to = stpcpy (to, "foo") 
to = stpcpy (to, "bar") 
printf ("%s\n", buffer) 
> 

C0NF0RMST0 

Thisfunction isnot part of theAN SI or POSIX standards, and isnot customary on U N IX systems, but isnota GN U 
invention either. Perhapsit comesfrom M S-DOS. 

SEE ALSO 

strcpy(3), bcopy(3), memccpy(3), memcpy(3), memmove(3) 

GNU,3Septemberl995 



strcasecmp, strncasecmp 

strcasecmp, strncasecmp— C ompare two strings, ignoring case 
SYNOPSIS 

(finclude <string.h> 

int strcasecmp(const char *s 1 , const char *s2); 

int strncasecmp(const char *sl, const char *s2, size_t n ) ; 

DESCRIPTION 

The strcasecmpo function comparesthetwo stri ngs s 1 and s 2 , ignoringthecaseof thecharacters. Itreturnsan integerless 
than, equal to, or greater than zero if si isfound, respectively, to belessthan, to match, or begreater than s2. 

Thestrncasecmpo function issimilar, except it only compares the first n characters of s 1 . 
RETURN VALUE 

The strcasecmp 0 and strncasecmp! ) functions return an integer lessthan, equal to, or greater than zero if si (or the first n 
bytesthereof ) isfound, respectively, to belessthan, to match, or begreater than s 2 . 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

bcmp(3), memcmp(3), strcmp(3), strcoll(3), strncmp(3) 

11 Aprii 1993 



strcat, strncat 

strcat, strncat— Concatenate two strings 
SYNOPSIS 

#include <string.h> 

char *strcat(char *dest , const char *src); 

char *strncat(char *dest , const char *src, size_t n ) ; 
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D ESC RIPTIO N 

Thestrcato function appendsthesrc stri ng to the d est string, overwritingthe \o character at the end of dest , and then 
adds a termi nati ng \a character. The stri ngsmay not overlap, and the dest string must haveenough space for the result. 

Thestmcato function issimilar, except that only thefirst n characters of s r c areappended todest . 
RETURN VALUE 

Thestrcato and stmcato functions return a pointerto the resulti ng string dest . 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 

GNU, 11 Aprii 1993 

strchr, strrchr 

strchr, strrchr— Locate character i n string 
SYNOPSIS 

#include <string.h> 

char *strchr(const char *s,int c); 

char *strrchr(const char *s,int c); 

DESCRIPTION 

Thestrchro function returns a pointerto the fi rst occurrenceof the character c i n the stri ng s . 
The strrchr o function returns a pointer to thelast occurrenceof the character c in the string s. 

RETURN VALUE 

Thestrchro and strrchr o functions return a pointerto thematched character or null if the character isnotfound. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

index(3), memchr(3), rindex(3), strpbrk(3), strsep(3), strspn(3), strstr(3), strtok(3) 

12 Aprii 1993 

strcmp, strncmp 

strcmp, strncmp— Compare two stri ngs 
SYNOPSIS 

#include <string.h> 

int strcmp(ccnst char *sl, const char *s2); 

int strncmp(const char *sl, ccnst char *s2, size_t n); 
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D ESC RIPTIO N 

Thestrcmpo function comparesthetwo stri ngs s 1 and s2.lt returnsan integer lessthan, equal to, or greater than zero if si 
isfound, respectively, to be lessthan, to match, or be greater than s 2 . 

Thestrncmpo function issimilar, exceptitonlycomparesthefirstn charactersof si. 
RETURN VALUE 

Thestrcmpo and stmcmpo functions return an integer lessthan, equal to, or greater than zero if si (orthefirstn bytes 
thereof ) isfound, respectively, to be lessthan, to match, or be greater than $2. 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

bcmp(3), memcmp(3), strcasecmp(3), strncasecmp(3), strcoll(3) 

11 Aprii 1993 

strcoll 

strcoii— Comparestwo stri ngs usi ng the current locale 
SYNOPSIS 

#include <string.h> 

int strcollfconst char *sl, const char *s2); 

DESCRIVO N 

The strcoii 0 function comparesthetwo stri ngs si and s 2 . It returnsan integer lessthan, equal to, or greater than zero if si 
isfound, respectively, to be lessthan, to match, or be greater than s2. Thecomparison isbased on stri ngs interpreted as 
appropri atefor the program 's current localefor category lc_collate. (See setiocaie(3)). 

RETURN VALUE 

Thestrcoiio function returnsan integer lessthan, equal to, or greater than zero if si isfound, respectively, to belessthan, 
to match, or be greater than 5 2 , when both are interpreted as appropri atefor the current locale. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

NOTES 

The Linux C Library currently hasn't implemented the complete PO SI X-col lati ng. 
In thePOSIX orC locales, strcoiio isequivalentto strcmpo. 

SEEALSO 

bcmp(3), memcmp(3), strcasecmp(3), strcmp(3), strxf rm(3), setlocale(3) 

GNU, 12 Aprii 1993 



strcpy, strncpy 

strcpy, strncpy— Copy a stri ng 



strdup 




SYNOPSIS 

(finclude <string.h> 

char *strcpy (char *dest , const char *src); 

char *strncpy(char *d est , const char *src, size_t n); 

D ESC RIFTIO N 

Thestrcpyo function copiesthe string pointed to besrc (including the termi nati ng \a character) to thearray pointed to by 
dest . The stri ngs may not overlap, and the desti nati on string dest must belargeenough to receive the copy. 

Thestrncpyo function issimi lar, except that not morethan n bytesof src arecopied. Thus, if thereisno nuli byteamong 
the fi rst n bytesof src, the resultwill not benull-terminated. 

In thecasewherethelength of src islessthan that of n, the remainder of dest will bepadded with nulls. 
RETURN VALUE 

Thestrcpyo and stmcpyo functions return apointerto the desti nati on stri ng dest. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

bcopy(3), memccpy(3), memcpy(3), memmove(3) 

GNU, 11 Aprii 1993 

strdup 

strdup— Duplicates a string 
SYNOPSIS 

#include <string.h> 

char *strdup(const char *s ) ; 

DESCRIPTION 

Thestrdupo function returns a pointer to a new string that is a dupli cateof the stri ngs. M emory for the new string is 
obtained with maiioc(3), and can befreed with t ree(3). 

RETURN VALUE 

Thestrdupo function returns a pointer to theduplicated string, orNun if insufficient memory wasavailable. 
ERRORS 

enomem I nsuff i ci ent memory avai I able to al I ocate dupli cate stri ng 

CONFO RMSTO 

SVID 3, BSD 4.3 

SEEALSO 

calloc(3), malloc(3), realloc(3), free(3) 

GNU, 12 Aprii 1993 
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strerror 

st rerror— Returns stri ng descri bi ng errar code 
SYNOPSIS 

#include <string.h> 

char *strerror(int errnum); 

DESCRIVO N 

The strerror o function returns a string descri bing the errar codepassed in theargument errnum. The string can only be 
used until the next cali to strerroro. 

RETURN VALUE 

The strerroro function returns the appropriate descri ption string, or an unknown errar messageif the errar code is 
unknown. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

errno(3), perror(3), strsignal(3) 

GNU, 13 Aprii 1993 

strfry 

strtry— Randomizes a stri ng 
SYNOPSIS 

(finclude <string.h> 

char *strf ry(char *string); 

DESCRI PTION 

The strtry o function randomizes the contentsof st ri ng by using rand(3) to randomly swap charactersin the string. The 
resultisan anagram of stri ng. 

RETURN VALUE 

Thestrfryo function returns a poi nterto the randomized string. 

C0NF0RMST0 

Thestrfryo function isuniqueto the Linux C Library and GN U C Library. 
SEE ALSO 

memf rob(3) 

GNU, 12 Aprii 1993 



strftime 

strftime— Formatsdate and time 
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SYNOPSIS 

#include <time.h> 

size t strf time (char *s , size_t max, const char 'format, 
const struct tm *t tu) ; 

D ESC RIPTIO N 

The strf time o function formatsthebroken-down timetm accordi ng to the format specificati on format and places the result 
i n the character array s of size ma x . 

0 rdi nary characters pi aced in theformat stringare copi ed to s withoutconversion. Conversion specifiers are introduced by a 
% character, and arereplaced in s asfollows: 

%a The abbrevi ated weekday name accordi ngto thecurrent locale 

%a Thefull weekday name accordi ngto thecurrent locale 

%b The abbrevi ated month name accordingto thecurrent locale 

%b Thefull month nameaccordingto thecurrent locale 

%c Thepreferred date and ti me representati on for thecurrent locale 

%d The day of the month as a decimai number (rangeOl to 31) 

%h Thehour as a decimai number usi ng a 24-hour clock (rangeOO to 23) 

%i Thehour as a decimai number usi ng a 12-hour clock (rangeOl to 12) 

%j Theday of theyearasadecimal number (range 001 to 366) 

%m The month as a decimai number (rangeOl to 12) 

%m Theminuteasadecimal number 

%p Either a.m. or p.m. accordingto thegiven timevalue, or the corresponding stri ngs for thecurrent 
locale 

%s Thesecond asadecimal number 

%u Theweek number of thecurrent year asadecimal number, starti ngwith the fi rstSunday as the first 
day of thefirstweek 

%w Theweek number of thecurrent year asadecimal number, starti ngwith the first M onday as the first 

day of thefirstweek 

%w T he day of theweek asadecimal, Sunday beingO 

%x Thepreferred daterepresentation forthecurrent localewithoutthetime 

%x Thepreferred timerepresentation forthecurrent locale without the date 

%y T he year as a deci mal number without a century (range 00 to 99) 

%y Theyearasadecimal number including the century 

%z Thetimezoneor nameorabbreviation 

%% A I iterai % character 

Thebroken-down timestructuretm isdefined in <time.h> asfollows: 

struct tm 
{ 

int tm sec; /* seconds */ 

int tm min; /* minutes */ 

int tm hour; /* hours */ 

int tm mday; /* day of the month */ 

int tm mon; /* month */ 

int tm year; /* year */ 

int tm wday; /* day of the week */ 

int tm yday; /* day in the year */ 

int tm isdst; /* daylight saving time */ 

}; 
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The members of the tm structure are 



tm_sec 


Thenumber of seconds after the minute, normally in therangeO to 59, but can beup to 
61 to allow for leap seconds 


tmjnin 


Thenumber of minutes after the hour, in therangeO to 59. 


tm_hour 


Thenumberof hourspast midnight, in therangeO to 23. 


tm_mday 


T he day of the month, in the range 1 to 31. 


tm_mon 


Thenumberof monthssincejanuary, intherangeOto 11. 


tm_year 


The number of years si nce 1900. 


tm_wday 


Thenumberof dayssinceSunday, in therangeO to 6. 


tm_yday 


Thenumberof days si ncejanuary 1, in therangeO to 365. 


tm_isdst 


A flag that indicateswhether daylight saving ti me is in effect at thetimedescribed. T he 
value is positive ifdaylightsaving ti me is in effect, zero if itisnot, and negativeif the 
information is not avai lable. 



RETURN VALUE 

Thestrttimeo function returns the number of characters placed in the array s, not including theterminating null character. 
If the value equals max, it means that the array wastoo small. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

date(l), time(2), ctime(3), setlocale(3), sprintf(3) 

NOTES 

The function supportsonly those locales specified in iocaie(7) 

GNU, 2 July 1993 

strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, 
strdup, strf ry, strlen, strncat, strncmp, strncpy, strncasecmp, 
strpbrk, strrchr, strsep, strspn, strstr, strtok, strxf rm, 
index, rindex 

strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, 
strpbrk, strrchr, strsep, strspn, strstr, strtok, strxf rm, index, rindex — Stri ng Operati Ons 

SYNOPSIS 

#include <string.h> 

int strcasecmp(const char *sl, const char *s2); 

char *strcat(char *dest, const char *src); 

char *strchr(const char *s,int c); 

int strcmp(const char *sl, const char *s2); 

int strcoll(const char *sl, const char *s2); 

char *strcpy(char *dest , const char *src); 

size_t strcspn(const char *s , const char *reject); 

char *strdup(const char *s ) ; 
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char *strfry(char *string); 
size_t strlen(const char *s ) ; 

char *strncat(char *dest , const char *src, size_t n ) ; 
int strncmp(const char *sl, const char *s2, size_t n); 
char *strncpy(char *dest , const char *src, size_t n ) ; 
int strncasecmp(const char *sl, const char *s2, size_t n ) ; 
char *strpbrk(const char *s , const char *a c c e p t ) ; 
char *strrchr(const char *s,int c); 
char *strsep(char "stringp, const char *d e I i m ) ; 
size_t strspn(const char *s , const char *a c c e p t ) ; 
char *strstr(const char *haystack, const char *n e e d ! e ) ; 
char *strtok(char *s , const char *d e I i m) ; 
size_t strxf rm(char *d e s t , const char *s r c , size_t n); 
char *i n d e x (const char*"s,i nt c); 
char *rindex(const char *s,int c); 

D ESC RIPTIO N 

Thestringfunctionsperform stri ng operationson NULL-terminated stri ngs. See the individuai man pagesfor descriptions of 
each function. 

SEE ALSO 

index(3), rindex(3), strcasecmp(3), strcat(3), strchr(3), strcmp(3), strcoll(3), strcpy(3), strcspn(3), strdup(3), strfry(3), 
strlen(3), strncat(3), strncmp(3), strncpy(3), strncasecmp(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3), 
strtok(3), strxfrm(3) 

9 Aprii 1993 

strlen 

stnen— C alculates the length of a stri ng 
SYNOPSIS 

#include <string.h> 

size_t strlen(const char *s); 

DESCRIVO N 

Thestrieno function calculates the length of the stri ngs, not includingthe terminati ng \o character. 

RETURN VALUE 

Thestrieno function returnsthenumber of characters in s . 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

string(3) 

12 Aprii 1993 

strpbrk 

strpbrk— Searches a stri ng for any of a set of characters 
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SYNOPSIS 

(finclude <string.h> 

char *strpbrk(const char *s , const char *a c c e p t ) ; 

DESCRIPTION 

Thestrpbrko function locates the first occurrencein the stri ngs of any of thecharacters in the stri ng a c c e p t . 
RETURN VALUE 

Thestrpbrko function returns a pointer to thecharacter in $ that matchesoneof thecharacters in acce pt . 
CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

index(3), memchr(3), rindex(3), strchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 

12 Aprii 1993 



strptime 

strptime— Convertsastring representati on of timeto a timetmstructure 
SYNOPSIS 

#include <time.h> 

char *strptime(char *buf , const char *f ormai, const struct tm *tm); 

DESCRIPTION 

strptime) ) i s the complementary function to strmmeo and converts thecharacter stri ng pointed to by buf to a timevalue, 
which isstored in thetm structu re pointed to by t m, using theformat specified by f o r ma t . format is a character string that 
consists of field descriptorsand text characters, reminiscent of scanf(3). Each field descriptor consistsof a% character 
followed by another character that specifies the replacement for the field descri ptor. Ali other characters are copied from 
f o r ma t i nto the result. T he foli ovvi ng field descri ptors are supported: 



%% 


Sameas%. 


%a, %A 


Dayofweek, using locale'sweekday names; either the abbrevi ated or full namemaybe 




specified. 


%b, %B, %h 


M onth, using locale's month names; either the abbreviated or full namemaybe 




specified. 


%c 


Date and timeas%x, %x. 


%c 


Dateandtime, in locale's long-format date and timerepresentation. 


%d, %e 


Day of month (1-31; leadingzeroesarepermitted but not required). 


%D 


Dateas%m/%d/%y. 


%H, %k 


Hour(0-23; leadingzeroesarepermitted but not required). 


%I, %1 


Hour(0-12; leadingzeroesarepermitted but not required). 


%] 


D ay number of year (001-366). 


%m 


Month number (1-12; leadingzeroes arepermitted but not required). 


%M 


M inute (0-59; leadingzeroesarepermitted but not required). 


%p 


Locale's equi valent of a.m. or p.m. 


%r 


Timeas%i:%M:%s %p. 



strsep 




%r Timeas%H:%M. 

%s Seconds(0-61; leading zeroes are permitted but not required; extra second allowed for 

leap years). 

%t Timeas%H:%M:%s. 

%w Weekday number (0-6) with Sunday as the first day of theweek. 

%x D ate, usi ng locale's date format. 

%x Time, usi ng locale's ti me format. 

%y Yearwithin century (0-99; leading zeroes are permitted but not required. 

U nfortunately, this makestheassumption that we are stuck in the 20th century, as 
1900 is automati cally added onto this number for the tm year field.) 

%y Year, includi ng century (for example, 1988). 



Caseisignored when matching itemssuch asmonth or weekday names. 
Thebroken-down timestructuretm isdefined in <time.h> asfollows: 

struct tm 
{ 

int tm_sec; /* seconds */ 

int tmjnin; /* minutes */ 

int tm_hour; /* hours */ 

int tm_mday; /* day of the month */ 

int tm_mon; /* month */ 

int tm_year; /* year */ 

int tm_wday; /* day of the week */ 

int tm_yday; /* day in the year */ 

int tm_isdst; /* daylight saving time */ 

}; 

RETURN VALUE 

Thestrptimeo function returns a pointer to thecharacter following thelast character in the stri ng pointed to bybuf . 
SEEALSO 

strftime(3), time(2), setlocale(3), scanf(3) 

BUGS 

The return values pointto static data, whosecontentsareoverwritten by each cali. 
NOTES 

This function isonly availablein libraries newer than versi on 4.6.5. 
Thefunction supportsonly thoselocalesspecified in iocaie(7). 

GNU,26Septemberl994 

strsep 

strsep— Extractstoken from stri ng 
SYNOPSIS 



#include <string.h> 

char *strsep(char "stringp, const char *delim); 
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DESCRIVO N 

Thestrsepo function returnsthenext token from the stri ng s t ri n g p which is delimitai by dei m. Thetoken i sterminateci 
with a \o character and st ri n g p isupdated to point past thetoken. 

RETURN VALUE 

Thestrsepo function returns a pointer to thetoken, or null if delira isnot found in st ri ngp. 
C0NF0RMST0 

BSD 4.3 

SEEALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strspn(3), strstr(3), strtok(3) 

GNU, 12 Aprii 1993 



strsignal 

strsignai— Returns stri ng describing signal 
SYNOPSIS 

#include <string.h> 

char *strsignal(int s ì g ) ; 

extern const char * const sys si gl i st [] 

DESCRIPTION 

Thestrsignaio function returns a stri ng describing the signal number passed in theargumentsi g. The stri ng can only be 
used until the next cali to strsignaio. 

Thearray sys_si gì i st holds the signal descri ption strings indexed by signal number. 
RETURN VALUE 

Thestrsignaio function returns the appropriate descri ption stri ng, or an unknown signal messageif the signal number is 
invalid. 

SEE ALSO 

psignal(3), strerror(3) 

GNU, 13 Aprii 1993 



strspn, strcspn 

strspn, strcspn— Search a stri ng for a set of characters 
SYNOPSIS 

#include <string.h> 

size t strspn(const char *s , const char *a c c e p t ) ; 
size t strcspn(const char *s , const char *reject); 



DESCRIPTION 

The strspn o function calculates the length of theinitial segment of s, which consistsentirely of characters in accept . 
The strcspn o function calculates the length of theinitial segment of s, which consistsentirely of characters not in re] ect 



RETURN VALUE 

Thestrspno function returnsthenumber of characters in theinitial segment of s, which consist only of charactersfrom 

accept . 

Thestrcspno function returnsthenumber of characters in theinitial segment of s, which arenot in the stri ng re] ect . 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strstr(3), strtok(3) 

12 Aprii 1993 

strstr 

strstr— Locatesa substring 
SYNOPSIS 

#include <string.h> 

char *strstr(const char "haystack, const char *n e e d I e ) ; 

DESCRIPTION 

Thestrstro function fi nds the first occurrence of the substri ng n e e d e i n the stri ng ha y s t ac k . T he terminati ng \o characters 
arenot compare! 

RETURN VALUE 

Thestrstro function returns a pointer to thebeginning of the substring, orNULL if the substring isnot found. 
SEEALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strtdk(3) 

GNU, 12 Aprii 1993 

strtod 

strtod— ConvertsASCII stri ng to doublé 
SYNOPSIS 

#include <stdlib.h> 

dduble strtdd(const char *nptr, char **endptr); 

DESCRIPTION 

The strtod o function converts theinitial portion of the stri ng pointed to by npt r to doublé representati on. 

Theexpected form of the stri ng is optional leadingwhitespaceaschecked by isspace(3), an optional plus (+) or minussign 
(-) followed by asequenceof di gits optionally containing a decimai point character, optionally followed by an exponent. An 
exponentconsistsof an e ore, followed by an optional plus or minussign, followed by a nonempty sequenceof di gits. If the 
locale isnot C or POSIX, differentformatsmay beused. 
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RETURN VALUES 

Thestrtod function returnstheconverted value, if any. 

If endpt r isnot null, a pointer to thecharacter after the last character used in the conversi on isstored in the location 
referenced byendptr. 

If no conversi on isperformed, zero isreturned and the value of n pt r isstored in the location referenced by endpt r . 

If the correct value would cause overflow, plusorminusHUGE_vAL isreturned (accordingto thesign of thevalue), and erange 
isstored in ermo. If the correct value would cause underflow, zero isreturned and erange isstored in ermo. 

ERRORS 

erange Overflow or underflow occurred. 

C0NF0RMST0 

ANSI C 

SEEALSO 

atof(3), atoi(3), atol(3), strtol(3), strtoul(3) 

BSD man page, 4 M ardi 1996 

strtok 

strtok— Extractstoken from string 
SYNOPSIS 

#include <string.h> 

char *strtok(char *s , const char *d e I i m ) ; 

DESCRIPTION 

A token is a nonempty string of charactersnot occurring in the string dei i m, followed by \a or by a character occurring in 

del i m. 

Thestrtoko function can beused to parse the stri ng s into tokens. The first cali to strtoko should haves asits first 
argument. Subsequent calls should have the first argument set to null. Each cali returns a pointer to the next token, or null 
when no more tokens are found. 

If a token endswith a del im iter, thi s deli miti ng character isoverwritten with a \n and a pointer to the next character issaved 
for the next cali to strtok. The del imi ter string dei i m may bedifferent for each cali. 

BUGS 

This function modifies its first argument. T he identity of the del imi ti ng character islost. 
RETURN VALUE 

Thestrtoko function returns a poi nterto the next token, or null if thereareno more tokens. 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strstr(3) 

GNU, 10 February 1996 
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strtol 

strtoi— Convertsastringto a long integer 
SYNOPSIS 

#include <stdlib.h> 

long int strtol(const char *nptr, char **endptr,int base); 

DESCRIVO N 

The strtoi o function converts the stri ng in nptr to a long integer value accordi ngto thegiven base, which must bebetween 
2 and 36 inclusive, orbe the speci al valueO. 

The stri ng must begin with an arbitrary amount ofwhitespace(as determi ned by isspace(3)) followed by a single optional + 
or - sign. If base iszero or 16, the stri ng may then include a ex prefix, and thenumber will beread in base 16; otherwise, a 
zero baseistaken aslO (decimai) unlessthenext character isO, in which caseit istaken as8 (octal). 

The remainder of the stri ng isconverted to a long int value in theobviousmanner, stoppi ngat the first character thatisnot 
a valid digit in the given base. (I n bases above 10, the letter a in either upper- or lowercase represents 10, b represents 11, and 
so forth, with z representing 35.) 

If endptr isnot null, strtoi (> stores the address of the fi rst invali d character in *endptr. If therewere no digitsat ali, strtoi o 
stores the originai value of nptr in *endptr. (Thus, if *nptr isnot \a but **endptr is\a on return, the enti re stri ng is valid.) 

RETURN VALUE 

The strtoi o function returns the result of the conversi on, unless the value would underflow or overflow. If an underflow 
occurs, strtoio returns long_min. If an overflow occurs, strtoi) ) returns long_max. In both cases, ermo is set to erange. 

ERRORS 

erange Thegiven stri ng wasout of range; the value converted hasbeen clamped. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

atof(3), atoi(3), atol(3), strtod(3), strtoul(3) 

BUGS 

Ignoresthecurrent locale. 

GNU, 10 Junel995 

strtoul 

strtoui— Convertsastringto an unsigned long integer. 
SYNOPSIS 

(finclude <stdlib.h> 

unsigned long int strtoul (const char *nptr, char "endptr, 
int base) ; 
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DESCRIVO N 

Thestrtouio function converts the stri ng in npt r to an unsigned long integer value accordi ngto thegiven base, which must 
bebetween 2 and 36 inclusive, or be the special valueO. 

The stri ng must begin with an arbitrary amount ofwhitespace(as determi ned by isspace(3)) followed by a single optional + 
or - sign. If base is zero or 16, the stri ng may then include a ax prefix, and thenumber will beread in base 16; otherwise, a 
zero baseistaken as 10 (decimai) unlessthenext character isO, in which caseit istaken as8 (octal). 

The remainder of the stri ng isconverted to an unsigned long mt value in theobvious manner, stoppi ng at the first character 
that isnot a valid digit in thegiven base. (In bases above 10, the letter a in either upper- or lowercaserepresents 10, b 
represents 11, and so forth, with z representing 35.) 

If endptr isnot null, strtouio stores the address of the fi rst i nvalid character in *endptr. If therewereno digitsat ali, 
strtouio stores the originai value of npt r in *endptr. (Thus, if *nptr isnot \0 but **endptr is\0 on return, the enti re stri ng is 
invalid.) 

RETURN VALUE 

Thestrtouio function returns either the result of the conversi on or, if therewasa leadingminussign, the negati on of the 
resultof the conversi on, unlesstheoriginal (non-negated) valuewould overflow; in the I after case, strtouio returns 
ulong_max and setsthe global variableer r no to erange. 

ERRORS 

erange Thegiven stringwasoutof range; the value converted hasbeen clamped. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEEALSO 

atof(3), atoi(3), atol(3), strtod(3), strtol(3) 

BUGS 

strtoui ignoresthecurrent locale. 

GNU, 29 March 1993 



strxfrm 

st rxt rm— Stri ng transformati on 
SYNOPSIS 

#include <string.h> 

size t strxf rm(char *dest , const char *src, size_t n); 

D ESC RIPTIO N 

Thestrxfrmo function transformsthesrc string into aform such that the result of strcmpo on two strings that havebeen 
transformed with strxtrmo isthesameasthe result of strcoiio on the two strings before their transformati on. Thefirst n 
charactersof thetransformed string areplaced in d e s t . The transformati on isbased on the program 'scurrent locale for 
category lc_collate. (Seesetiocaie(3)). 

RETURN VALUE 

Thestrxfrmo function returns thenumber of bytes required to sto re the transformed string in d e s t excludi ng the termi nat- 
ing \o character. If the value returned isn ormore, the contents of des t are indeterminate. 



sysconf 



CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

NOTES 

The Linux C Library currently hasn't implemented the complete PO SI X-col lati ng. 
In thePOSIX orC locale strxfrmo isequivalentto copying the stri ngwith stmcpy(). 

SEEALSO 

bcmp(3), memcmp(3), strcasecmp(3), strcmp(3), strcoll(3), setlocale(3) 

GNU, 12 Aprii 1993 

swab 

swab— Swaps adj acent bytes 
SYNOPSIS 

#include <string.h> 

void swab(const void *f r o m , void*to, size_t n); 

D ESC RIFTIO N 

Theswabo function copies n bytesfrom thearray pointed to by from to thearray pointed to by to, exchangingadjacent even 
and odd bytes. Thisfunction isused to exchangedata between machinesthathavedifferent low/high byteordering. 

RETURN VALUE 

Theswabo function returns no value. 

CONFORMSTO 

SVID 3, BSD 4.3 

SEEALSO 

bstring(3) 

GNU, 13 Aprii 1993 

sysconf 

sysconf— Getsconfiguration information atruntime 
SYNOPSIS 

#include <unistd.h> 
long sysconf(int name); 

DESCRIPTION 

sysconf o provides a way for the application to determi ne vai uesfor system limitsor optionsat runtime 

Theequivalent macrosdefined in <unistd.h> can only gi ve conservative values; if an application wantsto take advantage of 
valuesthat may change, a cali to sysconf o can bemade, which may yield more liberal resulta 

For getti ng information about a parti cular file, seetpathconf o or pathconf (). 

T he following values aresupported for name. First, the PO SIX.l_compatible values: 
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_SC_ARG_MAX 
_SC_CHILD_MAX 
_SC_CLK_TCK 
_SC_STREAM_MAX 

_SC_TZNAME_MAX 

_SC_OPEN_MAX 

_SC_JOB_CONTROL 

_SC_SAVED_IDS 

_SC_VERSION 

Next, the PO SI X. 2 values: 

_SC_BC_BASE_MAX 

_SC_BC_DIM_MAX 

_SC_BC_SCALE_MAX 

_SC_BC_STRING_MAX 

_SC_COLL_WEIGHTSJ«AX 

_SC_EXPR_NEST_MAX 
_SC_LINE_MAX 

_SC_RE_DUP_MAX 

_SC_2_VERSI0N 
_SC_2_DEV 
_SC_2_F0RT_DEV 
_SC_2_F0RT_RUN 



The maximum length of theargumentsto theexeco family of 
functions; thecorresponding macro ìsargjax. 
Thenumber of simultaneous processes per user ID; thecorresponding 
macro ìs_posix_child_max. 

Thenumber of clock ticks per second; thecorresponding macro is 

CLK_TCK. 

The maximum number of streamsthataprocesscan haveopen atany 
ti me. Thecorresponding POSIX macro ìsstream_max; the 
corresponding standard C macro ìsfopen_max. 
The maximum number of bytesin atimezonename; the 
corresponding macro ìstzname_max. 

The maximum number of filesthat a process can haveopen atany 
time; thecorresponding macro ìs_posix_open_max. 
This indicates whether POSIX-stylejob control issupported, the 
corresponding macro ìs_posix_job_control. 
Thisindicateswhetheraprocesshasasaved set-user-ID and asaved 
set-group-ID; thecorresponding macro ìs_posix_saved_ids. 
Indicates the year and month thePOSIX.l standard wasapproved in 
theformatYYYYHML; the valuei99009L indicates the most recent 
revision, 1990. 



Indicates themaximum obasevalueaccepted by thebc(l) utility; the 
corresponding macro ìsbc_base_max. 

Indicates themaximum valueof elementspermitted in an array by 

bc(l); thecorresponding macro ìsbc_dim_max. 

Indicates the maximum scalevalueallowed by bc(l); the 

corresponding macro ìsbc_scale_max. 

Indicates themaximum length of a stri ng accepted by bc{l); the 

corresponding macro ìsbc_string_max. 

Indicates the maximum numbersof weightsthat can beassigned to an 

entry of the lc_collate order keyword in the locale defini tion file; the 

corresponding macro ìscoll_weights_max. 

Isthemaximum number of expressionsthat can benested within 

parentheses by expr(l). Thecorresponding macro ìsexpr_nest_max. 

Themaximum length of a utility's input line length, eitherfrom 

standard input orfrom a fi le. T hi sincludes length fora trai li ng 

newl ine. Thecorresponding macro ìslinejiax. 

Themaximum number of repeated occurrences of aregular 

expression when theinterval notation \{m,n\} isused. Thevalueof 

thecorresponding macro ìsre_dup_max. 

Indicates the versi on of the PO SIX.2 standard in theformatof 

yyyyhhl. Thecorresponding macro ìsposix2_version. 

Indicates whether the POSIX. 2 C language development facilities are 

supported. Thecorresponding macro ìsposix2_c_dev. 

Indicates whether the POSIX.2 FORTRAN development Utilities are 

supported. Thecorresponding macro ìsposix2_fort_run. 

Indicates whether the POSIX. 2 FORTRAN runtimeutilitiesare 

supported. Thecorresponding macro ìsposix2_fort_run. 
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posix2_localedef I ndicates whether the PO SI X .2 creation of locate3viaiocaie(l) is 

supportai. Thecorresponding macro ìsposix2_localedef. 

_sc_2_sw_dev Indicate whether the PO SI X. 2 software development Utilities option 

issupported. Thecorresponding macro ìsposix2_sw_dev. 

RETURN VALUE 

Thevaluereturned is the valueof the system resource, 1 if aqueried option is avai lable, 0 if it isnot, or -1 on errar. The 
variaPleerrno isnot set. 

C0NF0RMST0 

POSIX.l, proposed POSIX.2 

BUGS 

It isdifficult use arg_max Pecauseit isnot speci fi ed how much of theargument space for execo isconsumed Py theuser's 
environment vari aPles. 

Some return ed values may Pe huge; they are not suitaPle for allocati ng memory. 

POSIX.2 isnot yet an approved standard; theinformation in thisman page is subject to change. 

SEE ALSO 

bc(l), expr(l), locale(l), f pathconf (3), pathconf(3) 

GNU, 18 Apri 1 1993 



closelog, openlog, syslog 

cioseiog, openlog, sysiog— Send messagesto the system logger 
SYNOPSIS 

#include <syslog.h> 

void openlog ( char *i dent , int option , Int f a c il i t y ) ; 
void syslog ( int priority, char *f o r ma t , ...); 
void closelog) void ) ; 

DESCRIPTION 

cioseiog o closesthe descriptor bang used to writeto the system logger. The use of cioseiog o isoptional. 

openlog o opens a connection to the system logger for a program. The string pointed to byi dent isadded to each message, 
and istypically set to the program name. Values for o pt i on and faci li ty aregiven in thenext subsection. The use of 
openlog o is optional; itwill automati cally becalled by sysiog o if necessary, in which casei dent will default to null. 

sysiog o generates a log message, which will bedistributed by sysiogd(8). priority isacombination of the f a c i i i t y and the 
i e v e i , values for which aregiven in thenext subsection. The remai ni ngarguments are a for mat , asin printf(3) and any 
arguments required by the f or mat , except thatthetwo characters%m will be replaced by the errar message string(strerror) 
correspondi ng to the present value of e r r n o . 

PARAMETERS 



Thissection lists the parameters used to set the values of opt on, f aci i i ty, and pr i or i ty 
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OPTION 

Theoption argumentto openiogo isan or of any of these: 

log cons W rite di rectly to system console if there isan errar whi le sendingto system logger 

log_ndelay Open the connection immediately (normally, theconnection isopened when the 

first messageislogged) 
log_perror P ri nt to stderr as wel I 

log_pid Include pid with each message 

FACI LI TY 

Thefacility argumentisused to specify whattypeof program islogging the message. T his lets the confi guration fi le specify 
that messagesfrom different faciliti eswill behandled differently. 



LOG_AUTH 


Security/authorization messages (deprecated use log_authpriv 
instead) 


LOG_AUTHPRIV 


Security/authorization messages (private) 


L0G_CR0N 


Clock daemon (cron and at) 


LOG_DAEMON 


Other system daemons 


LOG_KERN 


Kernel messages 


log_local0 through 


Reserved for locai use 


L0G_L0CAL7 




LOG_LPR 


Li ne printer subsystem 


L0G_MAIL 


M ail subsystem 


LOG_NEWS 


Usenet news subsystem 


LOG_SYSLOG 


M essages generated internai ly by sysiogd 


log_user (default) 


Generic user-level messages 


LOG_UUCP 


UUCP subsystem 



LEVEL 

T his determi nes the importanceof the message. The levels, in order of decreasi ng importance, are 



log_emerg 


System isunusable 


log_alert 


Action mustbetaken immediately 


log_crit 


Criticai conditions 


log_err 


Errar conditions 


log_warning 


Warning conditions 


log_notice 


N ormai, butsignificant, condition 


log_info 


Informational message 


log_debug 


Debug-leve! message 



HI STORY 

A sysiog function cali appeared in BSD 4.2. 
SEEALSO 

logger(l), sysiog. conf (5), syslogd(8) 

Linux, 15 February 1994 
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system 

system— Executes a shell command 
SYNOPSIS 

#include <stdlib.h> 

int system (const char * string); 

DESCRIPTION 

systemo executes a command specified in string by calli ng /bin/sh - c stri n g , and returns after the command hasbeen 
completed. Duringexecution of the command, sigchld will beblocked, and sigint and sigquit will beignored. 

RETURN VALUE 

Thevaluereturned is 1 27 if theexecveo cali for/bin/sh fails, -1 iftherewasanother errar, and the return codeof the 
command otherwise. 

If the valueof string ìsnull, system 0 returns non-zero if the shell isavailable, and zero if not. 
systemf ) does not affect the wait status of any other children. 

CONFO RMSTO 

ANSI C, POSIX.l, proposed POSIX.2, BSD 4.3 

BUGS 

Do not use system) ) from a program with suid or sgid privi leges, becausestrangevaluesfor someenvironmentvariables 
might beused to subvert system integri ty. U setheexec(2) family of functions instead, but not execip(2) or execvp(2). 

The check for the avai labi lity of /bin/sh isnot actually performed; it isalwaysassumed to beavailable. 

It is possi ble for the shell command to return 127, so that codeis not a sure indicati on that theexecveo cali failed; check 
ermo to makesure 

SEEALSO 

sh(l), exec(2), signal(2) 

GNU, 13 Aprii 1993 

tan 

tan— Tangent function 
SYNOPSIS 

#include <mat h . h> 
doublé tan(double x ) ; 

DESCRIPTION 

Thetano function returns the tangent ofx, wherex isgiven in radians. 
CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 
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SEEALSO 

acos(3), asin(3), atan(3), atan2(3), cos(3), sin(3) 

8 Junel993 



tanh 

tanti— H yperbolic tangent function 
SYNOPSIS 

#include <math.h> 
doublé tanh(double x ) ; 

DESCRIPTION 

T he tanh o function returns the hyperbolic tangent of x, which isdefined mathematically assinh(x) / cosh(x). 
C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

acosh(3), asinh(3), atanh(3), cosh(3), sinh(3) 

13 Junel993 

telldir 

teiidir— Returnscurrent location in directory stream 
SYNOPSIS 

#include <dirent.h> 
off t telldir(DIR *di r ) ; 

DESCRIPTION 

Theteiidiro function returns the cu rrent location associated with the directory stream di r . 
RETURN VALUE 

Theteiidiro function returns the cu rrent location in the directory stream or -1 if an erroroccurs. 
ERRORS 

ebadf Invalid directory stream descriptor d i r 

C0NF0RMST0 

BSD 4.3 

SEEALSO 

opendir(3), readdir(3), closedir(3), rewinddir(3), seekdir(3), scandir(3) 



31 M arch 1993 



termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetispeed, 

cfsetispeed, cfsetospeed, tcgetpgrp, tcsetpgrp 

tempnam 

tempnam— C reates a namefor a tempo rary file 
SYNOPSIS 

(finclude <stdio.h> 

char *tempnam(const char *dir, const char *pf x ) ; 

DESCRIVO N 

The tempnam o function generates a unique temporary filename using up to fivecharactersof pf x, if it is not null. The 
directory to placethefileissearched forin thefollowingorder: 

1. Thedirectory specified by theenvironment variableTMPDiR, if itiswritable 

2. Thedirectory specified bytheargumentdi r, if it is not null 

3. Thedirectory specified by p^tmpdir 

4. Thedirectory \tmp 

T he Storage for the filename is allocateci by maiioco, and so can befreed by the function freeo. 
RETURN VALUE 

The tempnam) ) function returns a pointer to the unique temporary filename, or null if a unique filename cannot be 
generated. 

ERRORS 

eexist Unableto generate a unique filename 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEEALSO 

mktemp(3), mkstemp(3), tmpnam(3), tmpf ile(3) 

GNU, 3 Apri 1 1993 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, 
tcflow, cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, 
cfsetospeed, tcgetpgrp, tcsetpgrp 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, 

cfsetospeed, tcgetpgrp, tcsetpgrp— Get and set terminal attributes, line control, get and set baud rate, get and set terminal 
foreground processgroup ID 

SYNOPSIS 

#include <termios.h> 
#include <unistd.h> 

int tcgetattr ( int f d , struct termios "termi osp ); 

int tcsetattr ( int f d , int optional_actions, struct termios *termios_p ); 

int tcsendbreak ( int f d , int durati o ri ); 

int tcdrain ( int f d ) ; 

int tcflush ( int fd.int queue_selector ); 
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int tcflow ( int f d ,int action ) ; 

int cfmakeraw ( struct termios *t e r mi 0 s _ p ); 

speed_t cfgetospeed ( struct termios "termi os p ); 

int cfsetospeed ( struct termios "termi osp, speed_t speed ); 

speed_t cfgetispeed ( struct termios «termi o s _ p ); 

int cfsetispeed ( struct termios "termi osp, speed_t speed ); 

pidt tcgetpgrp ( int f d ); 

int tcsetpgrp ( int fd, pid_t pgrpid ); 

D ESC RIFTIO N 

The termios functions describe a general terminal interface that is provided to control asynchronous Communications ports. 

M anyof the functions described herehaveater mi os_p argument that is a pointer to a termios structure. Thisstructure 
contai ns the following members: 

tcflagt ciflag; /* input modes */ 
tcflag_t c_oflag; /* output modes */ 
tcflag_t c_cflag; /* control modes */ 
tcflag_t c_lflag; /"localmodes*/ 
cc_t c_cc[NCCS]; /* control chars */ 

Thecitiag flag constantsare 

ignbrk Ignore break conditi on on input. 

brkint If ignbrk is not set, generate sigint on break condition, else read break as character \0. 

ignpar Ignore framing errors and parity errors 

parmrk If ignpar isnotset, prefix a character with a parity errar or framing errar with \377 \0. 

If neither ignpar nor parmrk is set, read a character with a parity errar or framing errar 
as \o. 

Enable input parity checking. 
Strip off eighth bit. 
Translate NLto cRon input. 
Ignore carriage return on input. 

Translate carri age return to newlineon input (unlessiGNCR is set). 
M ap uppercasecharactersto lowercaseon input. 
EnablexoN/xoFF flow control on output. 
Enable any character to restart output. 
EnablexoN/xoFF flow control on input. 
Ring beli when input queue isfull. 



INPCK 
ISTRIP 
INLCR 
IGNCR 
ICRNL 
IUCLC 
IXON 
IXANY 
IXOFF 
IMAXBEL 

T he c ot lag flag constants are 

OPOST 

OLCUC 

ONLCR 

OCRNL 

ONOCR 

ONLRET 

OFILL 

OFDEL 

NLDLY 

CRDLY 



Enable implementation-defined output processing. 
M ap lowercasecharactersto uppercaseon output. 
M ap nl to cr-nl on output. 
M ap cr to nl on output. 
D on't output cr at column 0. 
Don't output cr. 

Send fili charactersfora delay, rather than usingatimed delay. 
Fili character ìsascii del. If unset, fili character is asci 1 nul. 
N ewl ine delay mask. ValuesareNL© and nll 
Carriage return delay mask. Values are crb, cRi,CR2,or cr3. 



termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetispeed, 

cfsetispeed, cfsetospeed, tcgetpgrp, tcsetpgrp 




tabdly Horizontal tab delay mask. ValuesareTABo, tabi, tab2, tab3, or xtabs. A valueof xtabs 

expandstabsto spaces (with tab stops every eight columns). 
bsdly Backspace delay mask. ValuesareBse orBsi. 

vtdly Vertical tab delay mask. ValuesarevTo orvTi. 

ffdly Form feed delay mask. ValuesareFFo or ffl 

Thec_cfiag flag constantsare 

csize Character sizemask. Valuesarecss, cs6, cs7,or css. 

cstopb Set two stop bits, rather than one. 

cread Enable receiver. 

parenb Enable parity generation on output and parity checking for input. 

parodd Parity for input and output isodd. 

hupcl Lowermodem control lines after last processclosesthedevice(hangup). 

clocal Ignore modem control lines. 

cibaud M ask for input speeds(not used). 

crtscts Flow control. 

Thec_ifiag flag constantsare 

isig W hen any of the characters intr, quit, susp, or dsusp are received, generate the 

corresponding signal. 

i canon Enable canonical mode. Thisenables the special characters eof, eol, eol2, erase, kill, 

reprint, status, and werase, and buffers by lines. 
xcase If i canon isalso set, terminal isuppercaseonly. Input isconverted to lowercase, except 

for characters preceded by \. 0 n output, uppercase characters are preceded by \ and 

lowercase characters are converted to uppercase. 
echo echo input characters 

echoe If i canon isalso set, the erase character erases the precedi ng input character, and werase 

erases the precedi ng word. 
echok If i canon i s al so set, the kill character erases the current line. 

echonl If i canon i s al so set, echo theNL character even if echo isnotset. 

echoctl If echo isalso set, ascii control signalsother than tab, nl, start, and stop areechoed as 

"x, wherex is the character with ASCII code 0x10 greaterthan thecontrol signal. For 

example, character 0x28 (bs) isechoed as - h. 
echoprt If 1 canon and iecho arealso set, characters are pri nted asthey are bei ng erased. 

echoke If icanon isalso set, kill isechoed by erasingeach character on theline, asspecified by 

echoe and echoprt. 

flusho Output isbeingflushed. T hi s flag istoggled by typing the discard character. 

noflsh D isable flushi ng the input and output queueswhen generati ng the sigint and sigquit 

signals, and flushi ng the input queuewhen generati ng the sigsusp signal. 
tostop Send thesiGrrou signal to the processgroup of a background processthattries to write 

to its controlling terminal. 

pendin AH characters in the input queue are repri nted when thenext character isread. (oash 

handlestypeahead thisway.) 
iexten Enable implementation-defined input processing. 



tcgetattr) ) gets the parameters associated with theobject referred by fa and storesthem in the termios structurereferenced 
byt ermi os p . T hisfunction may beinvoked from a background process; however, the terminal attributesmay be 
subsequently changed by a foreground process. 
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tcsetattro sets the parameters associateci with the terminal (unlesssupport is required from theunderlying hardware that is 
notavailable) from thetermios structurereferred to by t e r mi o s _ p . optionai_actions specifieswhen thechangestakeeffect: 

tcsanow Thechangeoccurs immediately. 

tcsadrain T he change occurs after ali outputwritten to fd hasbeen transmitted. Thisfunction 

should be used when changi ng parameters that affect output. 

tcsaflush T he change occurs after ali outputwritten to theobject referred by fd hasbeen 

transmitted, and ali input that hasbeen received but not read will bediscarded 
before the change is made. 

tcsendbreako transmitsa conti nuousstream of zero-valued bits for a specific duration, if theterminal isusingasynchronous 
serial data tran sm issi on. If duration iszero, ittransmits zero-valued bits for at least 0.25 seconds, and not more that 0.5 
seconds. If duration isnot zero, itsends zero-valued bits for duration*N seconds, whereN isat least 0.25, and not morethan 
0.5. 

If theterminal is not usi ng asynchronous serial data transmission, tcsendbreako returns without taking any action, 
tcdrainowaitsuntil ali outputwritten to theobject referred to bytd has been transmitted. 

tcfiushodiscardsdata written to theobject referred to bytd but not transmitted, or data received but not read, depending 

On the vai ue Of queue_selector: 

tciflush Flushes data received but not read 

tcoflush Flushes data written but not transmitted 

tcioflush Flushes both data received but not read, and data written but not transmitted 

tcfiowosuspends transmission or reception of dataon theobject referred to bytd, dependi ngon thevalueof action: 
tcooff Suspends output 

tcoon Restartssuspended output 

tcioff Transmitsa stop character, which stops theterminal devicefrom transmitting 

data to the system 

tcion Transmitsa start character, which starts the terminal device transmitting data 

to the system 

T he default on open of a terminal fi le is that neither its input nor its output issuspended. 

Thebaud rate functions are provi ded for getti ng and setti ng the valuesof the input and output baud rates in thetermios 
structure. Thenew valuesdo not take effect until tcsetattro issuccessfully called. 

Setti ng the speed to bo instructs the modem to hang up. Theactual bit rate correspondingto B38400 may bealtered with 
setserial(8). 

Theinput and output baud rates are sto red in thetermios structure. 
cfmakeraw sets the terminal attributesasfollows: 

termioS_p->C_iflag &= " ( IGNBRK BRKINT | PARMRKj ISTRIP 
ì INLCRI IGNCR | ICRNL | IXON ) ; 
termios_p->c_of lag &= "OPOST; 

termios_p->c_lflag &= " (ECHO] ECHONL ] I CANON | ISIG | IEXTEN) ; 
termios_p->c_cf lag &= " (CSIZE ] PARENB) ; 
termios_p->c_cflag |=CS8; 

cfgetospeedo returns the output baud ratestored in thetermios structure poi nted to by termiosj. 

cfsetospeedo setstheoutput baud ratestored in thetermios structure poi nted to by termiosj to speed, which must beone 
of these constante 

B0 

B50 

B75 



tmpfile 



B110 
B134 
B150 
B200 
B300 
B600 
B1200 
B1800 
B2400 
B4800 
B9600 
B19200 
B38400 
B57600 
B1 15200 
B230400 

The zero baud rate, bo, isused to termi nate the connection. If bb isspecified, the modem control lines shall no longer be 
asserted. N ormally, thiswill disconnect the line cbaudex isa mask forthespeedsbeyond thosedefined in POSIX.l (57600 
and above). T hus, B57600 & cbaudex is non-zero. 

cfgetispeedo returnstheinput baud ratestored in thetermios structure. 

cfsetispeedo sets the input baud ratestored in thetermios structure to speed. If the input baud rate is setto zero, the input 
baud rate wi II beequal to the output baud rate. 

tcgetpgrpo returns process group ID of foreground processing group, or -1 on errar. 

tcsetpgrpo sets process group I D to pgrpid. pgrpid must be the I D of a process group in the samesession. 

RETURN VALUES 

cfgetispeedo returnstheinput baud ratestored in thetermios structure. 
ctgetospeedo returnstheoutput baud ratestored in the te rmios structure. 
tcgetpgrpo returns process group ID of foreground processing group, or -1 on errar. 
Ali otherfunctions return 
0 0 n success 

-1 On failureand set e r r n 0 to indicate the error 

SEEALSO 

setserial(8) 

Linux, 2 September 1995 



tmpfile 

tmpfile— C reates a temporary fi le 
SYNOPSIS 

#include <stdio.h> 
FILE *tmpfile (void) ; 

DESCRIPTION 

Thetmpfiief) function generatesaunique temporary fi lename usi ng the path prefix p_tmpdir defined in <stdio.h>.The 
temporary file isthen opened in binary read/write(w+b) mode. The file wi II beautomatically deleted when it isclosed or the 
program terminates. 
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RETURN VALUE 

Thetmpfiieo function returnsastream decriptar, or N ULL if auniquefilenamecannot Degenerato! ortheuniquefile 
cannot beopened. 



ERRORS 



EACCES 
EEXIST 
EMFILE 
ENFILE 
EROFS 



Search permission denied for directory in fi le's path prefix 
Unableto generate a unique filmarne 
Too many filedescriptors in use by process 
Too many files open in system 
Read-only fi I esystem 



CONFO RMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

mktemp(3), mkstemp(3), tmpnam(3), tempnam(3) 



GNU, 3 Aprii 1993 



tmpnam 

tmpnam— C reatesa namefor a temporary file 
SYNOPSIS 

#include <stdio.h> 
char *tmpnam(char *s ) ; 

DESCRIPTION 

Thetmpnamo function generates a unique temporary filenameusing the path prefix p_tmpdir defined in <stdio.h>. If the 
argument s ìsnull, tmpnam o returnstheaddressof an internai stati c areathat holds the filmarne, which isoverwritten by 
subsequent Calisto tmpnamo. If s isnot null, thefilenameisreturned in s. 

RETURN VALUE 

Thetmpnamo function returnsapointerto the unique temporary fi lename, or null if a unique name cannot begenerated. 
ERRORS 

eexist Unableto generate a unique filmarne 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEEALSO 

mktemp(3), mkstemp(3), tempnam(3), tmpf ile(3) 



GNU, 3 Aprii 1993 



toupper, tolower 



toascii 

toascii— C onverts character to ASC 1 1 
SYNOPSIS 

#include <ctype.h> 
int toascii (int c ) ; 

DESCRIPTION 

toascii( ) convertsc to a 7-bit unsigned char value that fits into the ASC II character set, by clearing the high-order bits. 

RETURN VALUE 

T he value returned isthatof theconverted character. 

C0NF0RMST0 

SVID.BSD 

BUGS 

M any peoplewill beunhappy if you usethisfunction. Thisfunction will convert accented lettersinto random characters. 
SEEALSO 

isascii(3), toupper(3), tolower(3) 

GNU, 16 September 1995 

toupper, tolower 

toupper, tolower— C onvert letter to uppercaseor lowercase 
SYNOPSIS 

#include <ctype.h> 
int toupper (int c ) ; 
int tolower (int c ) ; 

DESCRIPTION 

touppero converts the lettere to uppercase, if possible. 
toioweri ) converts the letter c to lowercase, if possible. 

RETURN VALUE 

The value returned isthatof theconverted letter, ore if the conversi on was not possible. 
C0NF0RMST0 

ANSI C, BSD 4.3 

BUGS 

Thedetailsof what constitutesan uppercaseor lowercase letter depend on thecurrent locale. For example, the default locale 
does not know about umlauts, so no conversion isdonefor them. 

In somenon-English locales, there are lowercase letters with no correspondinguppercaseequivalent; theGerman sharpsis 
one example. 
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SEEALSO 

isalpha(3), setlocale(3), locale(7) 

GNU, 4 Aprii 1993 

tsearch, tf ind, tdelete, twalk 

tsearch, tf ind, tdeiete, twalk— M anage a bi nary tree 
SYNOPSIS 

#include <search.h> 

void *tsearch (const void *key,void "rootp, 

int ( *c o mp a r ) (const void *, const void *)); 

void *tfind (const void *key, const void **rootp, 

int ("compar ) (const void *, const void *)); 

void *tdelete (const void *k e y ,void**r oot p , 

int ( *c o mp a r ) (const void *, const void *)); 

void twalk (const void *r o o t , void (*act i on ) (const void*n o de p , 

const VISIT whi eh , 

const int dept h ) ) ; 



DESCRIVO N 

tsearch, ttind, twalk, and tdeiete manage a bi nary tree. They are general ized from Knuth (6.2.2) Algorithm T. Thefirst 
field in each nodeofthetreeisapointertothecorrespondingdataitem. (T he cali ing program must store the actual data.) 
campar poi ntsto a compari son routine, which takespointersto two items. It should return an integer that is negative, zero, or 
positive, dependi ng on whether thefirst item islessthan, equal to, or greater than thesecond. 

tsearch searches the tree for an item. k e y pointsto the item to besearched for. rootp pointsto a vari able that poi ntsto the 
root of the tree. If the tree isempty, then the variable that r oot p pointsto should beset to null. If the item isfound in the 
tree, then tsearch returns a pointer to it. If it is notfound, then tsearch addsit, and returns a pointer to thenewly added 
item. 

ttind islike tsearch, exceptthat if theitem isnotfound, then ttind returns null. 
tdeiete deletesan item from the tree. Itsarguments are the sameas for tsearch. 

twalk performs depth-f i rst, left-to-right traversai of a binary tree. root pointsto the starting nodeforthetraversal. Ifthat 
nodeisnot the root, then only part of the tree wi II bevisited. twalk cai Is the user function action each ti me a nodeisvisited 
(that is, threetimesfor an internai node, and once for a leaf). acti on, in turn, takesthreearguments. Thefirst is a pointer to 
thenodebeing vi sited. Thesecond isan integer that takeson thevaluespreorder, postorder, and endorder dependi ngon 
whether thisis the fi rst, second, orthird vi atto the internai node, or leaf if it is the single vi si tto a leaf node. (Thesesymbols 
aredefined in <search.h>.) Thethird argument isthedepth of the node, with zero bei ng the root. 

RETURN VALUE 

tsearch returns a pointer to a matching item in the tree, orto thenewly added item, or null if therewas insufficient memory 
to add theitem. ttind returns a pointer to theitem, or null if no match isfound. Ifthere are multiple elements that match 
the key , theelement returned isunspecified. 

tdeiete return s a pointer to theparent of theitem deleted, or null if theitem was notfound. 
tsearch, ttind, and tdeiete also return null if rootp wasNULL on entry. 

WARNINGS 

twaik takes a pointer to the root, whi le the otherfunctionstake a pointer to a variable that pointsto the root. 

twalk uses postorder to mean "after the left subtree, but before the right subtree" Someauthoritieswould cali this morder, 
and reserve postorder to mean "after both subtrees." 



tsearch, tfind, tddete, twalk 



tdeiete frees the memo ry required for thenodein thetree. The user is responsi blefor freeing thememory for the 
corresponding data. 

The exam pi e program dependson thefact that twalk makes no further referenceto a node after calling the user function 
with argument endorder or ìeaf. This works with theGN U library implementati on, but isnot in theSysV documentation. 

EXAMPLE 

Thefollowing program insertstwelverandom numbersinto a binarytree, then printsthenumbersin order. Thenumbers 
are removed from thetree and their Storage freed during the traversai. 

#include <search.h> 
#include <stdlib.h> 
#include <stdio.h> 

void *root=NULL; 

void *xmalloc(unsigned n) 

{ 

void *p; 

p = malloc(n) ; 

if(p) return p; 

f printf (stderr, "insuf f icient memory\n" ) ; 
exit(1 ) ; 

} 

int compare(const void *pa, const void *pb) 

{ 

if(*(int *)pa < *(int *)pb) return -1; 
if(*(int *)pa > *(int *)pb) return 1; 
return 0; 

} 

void action(const void *nodep, const VISIT which, const int depth) 

{ 

int *datap; 
void *val; 

switch(which) 
{ 

case preorder: 

break; 
case postorder: 

datap = *(int **)nodep; 

printf ("%6d\n" , *datap); 

break; 
case endorder: 

datap = *(int **)nodep; 

(void)tdelete(datap, &root, compare); 

f ree(datap) ; 

break; 
case leaf: 

datap = *(int **)nodep; 

printf ("%6d\n" , *datap); 

vai = tdelete(datap, &root, compare); 

f ree(datap) ; 

break; 

} 

return; 
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} 

int main() 
{ 

int i, *ptr; 
void "vai; 



for (i = 0; i < 12; i++) 
{ 

ptr = (int *)xmalloc(sizeof (int) ) ; 
*ptr = rand()&0xff ; 

vai = tsearch( (void *)ptr, &root, compare); 
if(val == NULL) exit(1); 

} 

twalk(root, action); 
return 0; 

} 

C0NF0RMST0 

SVID 

SEEALSO 

qsort(3), bsearch(3), hsearch(3), lsearch(3) 

GNU, 24 September 1995 



ttyname 

ttyname— Returnsnameof a terminal 
SYNOPSIS 

#include <unistd.h> 

char *ttyname ( int des c ) ; 

D ESC RIFTIO N 

Retums a pointer to the pattinarne of the terminal devicethat isopen on the fi le descri ptor d e s c , or null on errar (for 
example, if desc isnotconnected to a terminai). 

CONFO RMSTO 

POSIX.l 

SEEALSO 

isatty(3), fstat(3) 

Linux, 20 Aprii 1995 



tzset 

tzset— I nitializes time conversion information 
SYNOPSIS 

#include <time.h> 
void tzset (void) ; 
extern char *t z n a me [2] ; 



tZSet 1059 

D ESC RIPTIO N 

Thetzseto function i n i ti al i zes th e t z n a me variablefrom theiz environment variable. Thisfunction isautomatically called 
by the other ti me conversi on functionsthatdepend on the ti me zone 

If the tz variable doesnot appear in the environment, thetzname variable is initialized with thebest approximation of locai 
wall clock time, asspecified by thetzme(5)-formatfile/usr/iib/zoneinfo/iocaitime. 

If the tz variable does appear in the environment but its value ìsnull or its value cannot beinterpreted using any of the 
formatsspecified in thefollowing paragraphs, Coordinated U ni versai Time (UTC) isused. 

T he value of tz can beone of threeformats. The first format isused when thereisno daylight savingtimein the locai time 
zone: 

s t d offset 

Thestd string specifiesthenameof the ti me zone and must bethreeor morealphabetic characters. The offset string 
immediately followsstd and specifies thetime valueto beadded to the locai timeto get Coordinated U ni versai Time 
(UTC). The offset ispositive if the locai ti me zone is west of the Prime M eridian and negative ifit iseast. Thehour must be 
between 0 and 24, and theminutesand secondsO and 59. 

Thesecond format isused when thereis daylight savi ng time: 

std offset dst [ off set ], start [ /time] ,end[ /time] 

T nere are no spaces in the specificati on. The ini ti al std and offset specify the standard ti me zone, asdescribed. The dst 
string and offset specify the name and offset for the corresponding daylight savi ngs ti me zone. If the offset isomitted, it 
defaults to one hour ahead of standard ti me. 

The start field specifies when Daylight SavingsTimegoes into effect and the end field specifies when thechangeismade 
back to Standard Time. These fi eldsmay havethefollowingformats: 

jn This specifies the Julian day with n between 1 and 365. February 29 isnever counted even in 

leap years. 

n T his specifies thej ul ian day with n between 1 and 365. February 29 iscounted in leap years. 

Mm. w. d T his specifies day d (0 <=d <=6) of week * (1 <=w <=5) of month m (1 <=m <=12). Week 

1 is the first week in which day d occursand week 5 isthe last week in which dayd occurs. 

Day 0 isaSunday. 

Thetimefields specify when, in thelocal timecurrently in effect, thechangeto the other ti me occurs. If omitted, the default 

ÌS 02:00:00. 

Thethird format specifies that the ti me zone informati on should beread from a fi le 
: [filespec] 

If the file specification filespec isomitted, thetimezoneinformation is read from /usr/iib/zoneinfo/iocaitime, which isin 
tzfiie(5) format. If filespec isgiven, it specifies an-other tzfiie(5)-formatfileto read thetimezoneinformation from. If 
filespec does not begin with a/, the fi le specification is relative to the system time con versi on information directory /usr/ 

lib/zoneinf o. 

FILES 

/usr/iib/zoneinfo System time zone directory 

/usr/lib/zoneinfo/localtime Locai timezonefile 

/usr/lib/zoneinfo/posixrules Rulesfor PO SlX-Style TZS 

CONFO RMSTO 

SVID 3, POSIX, BSD 4.3 
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SEEALSO 

date(l), gettimeofday(2), time(2), ctime(3), getenv(3), tzfile(5) 

BSD, 2 July 1993 



none 

none— U ndocumented library functions 

SYNOPSIS 

U ndocumented library functions 

D ESC RIPTIO N 

Thisman pagementionsthoselibrary functionsthat areimplemented in thestandard libraries but notyet documented in 
man pages. 

SO LI C ITATI ON 

If you have informati on aboutthese functions, pleaselook in the source code, writea man page (usi ng a style si milar to that 
of theother Linux section 3 man pages), and send itto aeb@cwi.ni for inclusion in thenext man page rei ease. 

THE LIST 

des_setparity, dn_skipname, ecb_crypt, encrypt, endnetgrent, endrpcent, endutent, execlp, fcrypt, fp_nquery, fp_query, 
fp_resstat, get_myaddress, getnetgrent, getnetname, getopt_long_only, getpublickey, getrpcbyname, getrpcbynumber, 
getrpcent, getrpcport, getsecretkey, getutid, getutline, h_errlist, host2netname, hostalias, inet_nsap_addr, 
inet_nsap_ntoa_init_des, innetgr, key_decryptsession, key_encryptsession, key_gendes, key_setsecret, lfind, libc_nls_init, 
lockf, lsearch, mcheck, memalign, mstats, mtrace, netname2host, netname2user, nlist, obstack_f ree, p_cdname, p_cdnname, 
p_class, p_fqname, p_option, p_query, p_rr, p_time, p_type, passwd2des, pmap_getmaps, pmapjetport, pmap_rmtcall, pmap_set, 
pmap_unset, putlong, putshort, pututline, rcrad, re_compile_f astmap, re_compilejattern, re_match, re_match_2, re_rx_search, 
re_search, re_search_2, re_set_registers, re_set_syntax, registerrpc, res_send_setqhook, res_send_setrhook, rexec, 
rresvport, rtime, ruserok, ruserpass, setfileno, sethostfile, setkey, setlogmask, setnetgrent, setrpcent, setutent, 
siglongjmp, snprintf, stpcpy, svc_exit, svc_getreq, svc_getreqset, svc_register, svc_run, svc_sendreply, svc_unregister, 
svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth, 
svcfd_create, svcraw_create, svctcp_create, svcudp_buf create, svcudp_create, svcudp_enablecachesyscall, tdelete, teli, 
tfind, timegm, tr_break, tsearch, twalk, tzsetwall, uf c_dof inalperm, ufc_doit, user2netname, utmpname, valloc, vsnprintf, 
vsyslog, xdecrypt, xdr_accepted_reply, xdr_array, xdr_authdes_cred, xdr_authdes_verf, xdr_authunix_parms, xdr_bool, 
xdr_bytes, xdr_callhdr, xdr_callmsg, xdr_char, xdr_cryptkeyarg, xdr_cryptkeyres, xdr_datum, xdr_des_block, xdr_domainname, 
xdrjlouble, xdr_enum, xdr_float, xdr_free, xdr_getcredres, xdr_int, xdr_keybuf, xdr_keystatus, xdr_long, xdrmapname, 
xdr_netnamestr, xdr_netobj, xdr_opaque, xdr_opaque_auth, xdr_passwd, xdr_peername, xdr_pmap, xdr_pmaplist, xdr_pointer, 
xdr_ref erence, xdr_rejected_reply, xdr_replymsg, xdr_rmtcall_args, xdr_rmtcallres, xdr_short, xdr_string, xdr_u_char, 
xdr_u_int, xdr_u_long, xdr_u_short, xdr_union, xdr_unixcred, xdr_vector, xdr_void, xdr_wrapstring, xdr_yp_buf, 
xdr_yp_inaddr, xdr_ypbind_binding, xdr_ypbìnd_resp, xdr_ypbind_resptype, xdr_ypbind_setdom, xdr_ypdelete_args, 
xdr_ypmaplìst, xdr_ypmaplist_str, xdr_yppasswd, xdr_ypreq_key, xdr_ypreq_nokey, xdr_ypresp_all, xdr_ypresp_all_seq, 
xdr_ypresp_key_val, xdr_ypresp_maplist, xdr_ypresp_master, xdr_ypresp_order, xdr_ypresp_val, xdr_ypstat, 
xdr_ypupdate_args, xdrmem_create, xdrrec_create, xdrrec_endof record, xdrrec_eof, xdrrec_skiprecord, xdrstdio_create, 
xencrypt, xprt_register, xprt_unregister, yp_all, yp_bind, yp_first, yp_get_def ault_domain, yp_maplist, yp_master, yp_match, 
yp_next, yp_order, yp_unbind, yp_update, yperr_string, ypprot_err 



Linux 1.3.15, 25 August 1995 
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usleep 

usieep— Suspendsexecution for interval of microseconds 
SYNOPSIS 

«include <unistd.h> 

void usleep(unsigned long usec); 

DESCRIPTION 

Theusieepo function suspendsexecution of the calli ng process for usec microseconds. The sleep may belengthened slightly 
by any system activity or by thetimespent processing the cali. 

CONFO RMSTO 

BSD 4.3 

SEEALSO 

setitimer(2), getitimer(2), sleep(3), alarm(3), select(3) 

4 July 1993 

wcstombs 

wcstombs— C onverts a wide character stri ng to a multi byte character stri ng 
SYNOPSIS 

#include <stdlib.h> 

size_t wcstombs (char *s , const wchar_t *pwcs, size_t n); 

DESCRIPTION 

The wcstombso function convertsasequenceof widecharactersfrom thearray pwcs into asequenceof multi byte characters 
and stores up to n bytes of multi byte characters i n the array s . 

RETURN VALUE 

wcstombso returnsthenumberof bytes stored in s or-1 ifs containsan invalid wide character. 
C0NF0RMST0 

SVID 3, ISO 9899 

SEEALSO 

mblen(3), mbtowc(3), mbstowcs(3), wctomb(3) 

GNU, 29 March 1993 

wctomb 

wctomb— C onverts a wide character to a multi byte character 
SYNOPSIS 

«include <stdlib.b> 

int wctomb(cbar *s , wcbarjt wchar); 
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Thewctombo function convertsawidecharacterwchar into a multi byte character and, if s is not null, stores the multi byte 
character representation in s . 

RETURN VALUE 

wctombo returnsthenumber of bytesin the multi byte character or -1 if the wi de character isnot valid. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEEALSO 

mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3) 

GNU, 29 March 1993 
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INTR0DUCTI0N 

Thispart describes special files. 

FILES 

lievi* Device files 

AUTHORS 

Look at theheader of themanual page for the author(s) and copyright conditions. N otethat thesecan bedifferent from page 
to page. 

Linux, 24 J uly 1993 

charsets 

charsets— Programmer'sview of character setsand internati onalization 
DESCRIPTION 

Linux is an international operating system. Several of its Utilities and devi ce drivers (includi ng the console driver) support 
multi linguai character sets includi ng Lati n-alphabet letterswith di acri ti cai marks, accents, ligatures, and enti re non-Latin 
alphabets including Greek, Cyrillic, Arabie, and H ebrew. 

This manual page presents a programmer's-eye view of different character-set standardsand how they fit together on Linux. 
StandardsdiscussedincludeASCIIJSO 8859, KOI8-R, Unicode, ISO 2022, and ISO 4873. 

ASCII 

ASCII (American Standard Code for Information) is the originai 7- bit character set, originally designed for American 
English. It iscurrently described by theECMA-6 standard. 

An ASCII variant replacing the American crosshatch/octothorpe/hash pound symbol with the British pound-sterling symbol 
isused in G reat Britain; when needed, the American and British variantsmay be disti nguished asU .S. ASCII and U .K. 
ASCII. 

As Linux waswritten for hardware designed in theU nited States, it natively supportsU .S. ASCII. 
ISO 8859 

ISO 8859 isaseriesof 10 8- bit character sets, ali of which have U.S. ASCII in thar low (7-bit) half, invisible control 
charactersin positions 128 to 159, and 96 fixed-width graphics in positions 160-255. 

Of these, themost important islSO 8859-1 (Lati n-1). It is natively supported in the Linux console driver, fairly well 
supported in X11R6, and isthe base character set of H TM L. 

C onsole support for the other 8859 character sets isavailable under Linux through user-mode Utilities (such assetfont(8)) 
that modify keyboard bindingsand theEGA graphics table and employ the "user mapping" font table in the console driver. 

H ere are brief descriptions of each set: 

8859-1 (Latin-1) Lati n-1 covers most Western European languagessuch asAlbanian, Catalan, Danish, 

Dutch, English, Faroese, Finnish, French, German, Galician, Irish, Icelandic, I tal i an, 
N orwegian, Portuguese, Spanish, and Swedish. Thelack of the ligatures D utch ij, 
French oe, and old-styl e German quotation marks istolerable. 

8859-2 (Latin-2) Latin-2 supports most Latin-written Slavic and Central European languages: Czech, 

German, H ungarian, Polish, Rumanian, Croatian, Slovak, and Slovene 

8859-3 (Latin-3) Latin-3 is popular with authorsof Esperanto, Galician, M altese, and Turkish. 

8859-4 (Latin-4) Latin-4 introduced lettersfor Estonian, Latvian, and Lithuanian. It is essenti al ly 

obsolete; see 8859-10 (Latin-6). 
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8859-5 Cyrillic letters supporti ng Bulgarian, Byelorussian, M acedonian, Russian, Serbian, and 

Ukrainian. U krainians read the letter ghewith downstrokeasheh and would need aghe 
with upstroketo writea correct ghe. (Seethediscussion of KOI8-R in thenext 
subsection.) 

8859-6 Supports Arabie. The 8859-6 glyph tableisafixed font of separate letter forms, but a 

proper display engineshould combinethere pai rwise into initial, mediai, and final 
forms. 

8859-7 Supports modem Greek. 

8859-8 Supports H ebrew. 

8859-9 (Latin-5) Thisisa variant of Latin-1 that replaces rarely used Icelandic letters with Turkish ones. 

8859-10 (Latin-6) Latin-6 addsthe last Inuit (Greenlandic) and Sami (Lappish) letters that werem issi ng in 

Latin 4 to cover the enti re N ordic area. RFC 1345 listed a preliminary and different 
Latin 6. Skolt Sami stili needsafew moreaccentsthan these. 



K0I8-R 

KOI8-R is a non-I SO character set popular in Russia. The lower half isti .S. ASCII; the upper is a Cyrillic character set 
somewhat better design ed than ISO 8859-5. 

Console support for KO 18-R isavailable under Linuxthrough user-mode Utilities that modify keyboard bindingsand the 
EGA graphics table, and that employ the "user mapping" fonttablein the console driver. 

UNICODE 

Unicode (ISO 10646) is a standard that aimsto unambiguously represent every known glyph in every human language. 
Unicode's native encoding i s 32-bit (older versionsused 16 bits). Information on U ni code isavailable at http: //www. 

unicode.com. 

Linux representsU nicode using the 8-bit U nicodeTransfer Format (UT F-8). UTF-8 isa variable length encoding of 
U nicode. It usesl byteto code 7 bits, 2 bytesfor 11 bits, 3 byte for 16 bits, 4 bytesfor 21 bits, 5 bytesfor 26 bits, and 
6 bytesfor 31 bits. 

Let e, 1, x stand for azero, one, or arbitrary bit. A byteoxxxxxxx standsfor the U nicode 00000000 oxxxxxxx, which codesthe 
samesymbol as the ASC 1 1 0xxxxxxx. Thus, ASCII goesunchanged into UTF-8, and peopleusing only ASCII do notnotice 
any change— not in code, and not in fi I e si ze. 

A bytenoxxxxx is the start of a 2-bytecode, and noxxxxx loyyyyyy isassembled into 00000XXX xxyyyyyy. A bytem0xxxx is 
the start of a 3- byte code, and moxxxx loyyyyyy i0zzzzzz isassembled into xxxxyyyy yyzzzzzz. (W hen utf-8 isused to code 
the 31-bit ISO 10646, then this progression conti nuesup to 6-bytecodes.) 

For ISO -8859-1 users this means that the characters with high bit set now arecoded with two bytes. This tend sto expand 
ordinary textfilesby oneortwo percent. T nere are no conversion problems, however, si nce the U nicode valueof ISO -8859- 
1 symbols equals their ISO -8859-1 value(extended by eight leadingzero bits). F or Japanese users, this means that the 16-bit 
codesnow in common usewill taketh ree bytes, and extensive mapping tables are required. M anyjapanesethereforeprefer 
iso 2022. 

N ote that UTF-8 isself-synchronizing: ioxxxxxx isatail, any other byte is the head of a code. N ote that the only way ASC II 
bytes occur in a UTF-8 stream isasthemselves. In particular, thereareno embedded Nuisor /s that form part of somelarger 
code. 

BecauseASCII, and, in particular, nul and /, areunchanged, the kernel doesnot notice that UTF-8 is being used. It doesnot 
careat ali what the bytes it ishandling stand for. 

Rendering of Uni code data streams is typically handled through subfont tables that map a subset of U ni code to glyphs. 
Internally, the kernel usesU nicode to describe the subfont loaded in video RAM . This means that in UTF-8 mode one can 
use a character set with 512 different symbols. This is not enough for Japanese, Chinese, and Korean, but it isenough for 
most other purposes. 
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ISO 2022 AND ISO 4873 

ThelSO 2022 and 4873 standards descri bea font-control model basedonVTlOO practice. This model is(partially) 
supported by the Linux kernel and by xterm(l). It is popular in Japan and Korea. 

Therearefour graphic character sets, called G0, GÌ, G2, and G3, and oneof them isthecurrent character set for codeswith 
high bit zero (initially G0), and oneof them isthecurrent character set for codeswith high bit one (initially GÌ). Each 
graphic character set has94 or 96 characters, and is essenti al ly a 7-bit character set. It uses codes either 040-0177 (041-0176) 
or 0240-0377 (0241-0376). G0 always has size 94 and uses codes 041-0176. 

Switching between character sets is done usi ng theshift functions "N (soori_si),"0 (si or lsb), esc n (ls2), esc 0 (LS3), esc 
n (SS2), 

esc o(ss3),esc " (lsir), esc } (ls2r), esc | (ls3r). T he function LSn makes character set G n the current one for codes with 
high bit zero. The function i_snR makes character set Gn the current one for codeswith high bit one. The function ssn makes 
character set G n (n=2 or 3) the current one for the next character only (regardless of the vai ue of its high order bit). 

A 94-character seti s desi gnated asGn character set byan escape sequence esc < xx(forGO), esc > xx(forGl), esc * xx(for 
G2), esc + xx (for G3), wherexx is a symbol or a pair of symbolsfound in the ISO 2375 International Register of Coded 
C haracter Sets. For example, esc ( @ selects thelSO 646 character set asGO, esc ( a selects the U .K. standard character set 
(with pound instead of number sign), esc <b selects ASC 1 1 (with dollar instead of currency sign), esc ( m selects a character 
set for African languages, esc ( 1 a selects the Cuban character set, and so on. 

A 96-character set is desi gnated asGn character set byan escape sequence esc - xx (for GÌ), esc . xx (for G 2) or esc / xx 
(forG3). For example, esc - GselectstheHebrewalphabetasGl. 

A multi byte character set is desi gnated asGn character set by an escape sequence esc $ xx or esc $ ( xx(forGO), esc $ ) 
xx (for GÌ), esc $ * xx (for G2), esc $ + xx (for G3). For example, esc $ ( c selects the Korean character set for G0. The 
Japanese character set selected by esc $ b has a more recent version selected byEsc & @esc $ b. 

ISO 4873 stipulates a narrower use of character sets, whereGO isfixed (always ASC II), so that GÌ, G2, and G3 can only be 
invoked for codeswith the high order bit set. In particular, "N and "0 arenotusedanymore, esc ( xx can beused only with 
xx=B, and esc ) xx, esc * xx, esc + xx areequivalent to esc - xx, esc . xx, and esc / xx, respectivdy. 

SEEALSO 

console(4), console_ioctl(4), console_codes(4) 

Linux, 5 N ovember 1996 



console 

consoie— Consoleterminal and virtual consoles 
D ESC RIFTIO N 

A Linux system hasup to 63 virtual consoles (character deviceswith major number 4 and minor number 1 to 63), usuai ly 
called /dev/ttyn with 1 n 63. T he current console is also addressed by /dev/consoie or /dev/ttye, thecharacter device with 
major number 4 and minor number 0. The devi ce files /dev/* are usually created using the script makedev, or using mknod(l), 
usually with mode 0622 and owner root.tty. 

Beforekernel version 1.1.54, thenumber of virtual consoles was compi led into the kernel (in tty.n: #define nr_consoles s) 
and could bechanged by editing and recompiling because version 1.1.54 virtual consoles are created on-the-fly, assoon as 
they are needed. 

Common waysto start a processon a console are the following: 

■ Teli init(8) (in inittab(5)) to start a getty(8) on the console 

■ Ask open(l) to start a process on the console 

■ Start x; it will find the first unused console and display its output th ere. (There is also the ancient dosneii(8).) 



consolecodes 



Common waysto switch consoles arethefollowing: 

■ U se Alt+Fn or Ctrl-tAlt-tf n to switch to console n; AltGr+Fn might bringyou to console n+12 [nere Alt and AltGr refer 
to the left and ri ght Alt keys, respectivdy] 

■ U se Alt+RightArrow or Alt-HeftArrow to cyclethrough the presently allocated consoles 

■ Use the program chvt(l). (Thekey mappingcan beset by the user; seeioadkeys(l); the precedi ng key combinationsare 
accordi ng to the default settings.) 

Thecommand disaiioc(8) will freethememory taken by thescreen buffersfor consoles that no longer haveany associ ated 
process. 

PROPERTIES 

Consoles carry alotof state. I hopeto document that some other ti me. The mosti mportantfactis that the consoles simulate 
vtlOO termi nals. In particular, a console is reset to the i nitial state byprinting the two characters ESC c.AII escape sequences 
can befound in console codes(4). 

FILES 

/dev/console 
/dev/tty* 

SEEALSO 

charsets(4), console_codes(4), console_ioctl(4), mknod(l), tty(4), ttys(4), getty(8), init(8), chvt(l), open(l), disalloc(8), 
loadkeys(l), resizecons(8), setfont(8), mapscrn(8) 

Linux, 31 October 1994 

console_codes 

consoie_codes— Linux console escape and control sequences 
D ESC RIFTIO N 

T he Linux console implements a large subset of the VT 102 and ECM A-48/ISO 6429/AN SI X3.64 terminal controis, plus 
certain private-mode sequences for changing the color palette, character-set mapping, and so on. In the followi ng tabular 
descriptions, thesecond column givesECM A-48 or DEC mnemonics(thelatter if prefixed with D EC) for the given 
function. Sequenceswithout a mnemonicareneither ECM A-48 norVT102. 

After ali thenormal output processing has been done, and astream of characters arri vesat the console driver for actual 
printing, the first thingthat happens isatranslation from the code used for processingto thecodeused for printing. 

If the console is in UTF-8 mode, then theincoming bytes are first assembled into 16-bitU nicodecodes. 0 therwise, each 
byte is tran sform ed accordi ngto thecurrent mapping table (whi eh translates it to aU nicodevalue). (Seethe"Character Sets" 
subsection fordiscussion.) 

In thenormal case, the U nicodevalue isconverted to a font index, and this is stored in video memory, so that the corre- 
spondingglyph (asfound in video ROM ) appearson thescreen. N otethattheuseof U ni code (and the design of the PC 
hardware) allows the use of 512 different glyphs simultaneously. 

If the current U nicodevalue is a control character, oryou arecurrently processing an escape sequence, the value will treated 
speci ally. Instead of beingturned into a font index and rendered asaglyph, it may trigger cursor movement or other control 
functions. (See the "Linux Console Controls" subsection.) 

It is general ly not good practiceto hardwi re terminal controis into programs. Linux supportsaterminfo(5) database of 
terminal capabilities. Rather than emitting console escape sequences by hand, you will almost alwayswant to use a 
terminfo-awarescreen library or utility such asncurses(3), tput(l), or reset(l). 
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LINUX CONSOLE CONTROLS 

This section describes ali the control characters and escape sequencesthat invoke special functions(that is, anything other 
than writing aglyph atthecurrent cursor location) on the Linux console. 

CONTROL CHARACTERS 

A character is a control character if (Peforetransformation accordi ngto the mapping table) it hasoneof the 14 codesoa 
(nul), 07 (bel), 08 (bs), 09 (ht), 0a (lf), 0b (vt), 0c (ff), 0<j (cr), 0e (so), of (si), 18 (can), ia (sub), ib (esc), 7f (del). Onecan 
set a display control characters mode (seePelow), and allow 07, 09, 0b, ia, ia, 71 to Pedisplayed asglyphs. On the other 
hand, in UTF-8 mode ali codes00-if areregarded as control characters, regardlessof any display control characters mode. 

If you have a control character, it isacted upon immediately and then discarded (even in the middle of an escape sequence) 
and the escape sequence conti nueswith the next character. (H owever, esc startsa new escape sequence, possi Ply aPorting a 
previ ousunfinished one, and can and sub aPort any escape sequence) Therecognized control characters are bel, bs, ht, lf, 
vt, ff, cr, so, si, can, sub, esc, del, csi. They do what onewould expect: 

bel (0x07, "g) beeps. 

bs (0x08, "h) backspacesonecolumn (butnotpast the beginningof the line). 

ht (0x09, "1) goesto the next tab stop orto the end of the line if thereis no earlier tab stop. 

lf (0x0A, "j), vt (0x0B, "k) and ff <0x0c, "l) ali givea linefeed. 

cr (0x0D, "m) gives a carri age return. 

so (0x0E, "n) activatestheGl character set, and if lf/nl (new line mode) is set, also a carri age return. 

si (0x0F, "0) arti vates the GO character set. 

can (0x18, "x) and sub (0xia, "z) interrupt escape sequences. 

esc (0x1 b, •[) startsan escape sequence. 

del (0x7f) isignored. 

csi (0x9b) isequivalentto esc [. 



ESC SEQUENCES, NOTCSI SEQUENCES 



ESC c 
ESC D 
ESC E 
ESC H 
ESC M 
ESC Z 

ESC 7 

ESC 8 
ESC [ 
ESC % 
ESC % ? 
ESC % G 
ESC % 8 
ESC # 8 
ESC ( 
ESC ( B 
ESC ( 0 



RIS 
IND 
NEL 
HTS 
RI 

DECID 

DECSC 

DECRC 
CSI 



DECALN 



Reset. 
Linefeed. 
N ewline. 

Set tab stop at current column. 
Reverse linefeed. 

DEC private identificati on. The kernel returns the stri ng 

esc [ ? 6 c, claiming that it is a VT 102. 

Save current state (cursor coordinates, attributes, character 

sets). 

Restare most recently saved state. 

Control sequence introducer. 

Start sequence selecti ng character set. 

Sdect default (ISO 646/ ISO 8859-1). 

Sei ect UTF-8. 

Sdect UTF-8 (obsolete). 

DEC screen alignment test: fili screen with Es. 

Start sequence defining G0 character set. 

Select default (ISO 8859-1 mapping). 

Sei ect vtlOO graphics mapping. 
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esc ( u Select nuli mapping— straight to character ROM . 

esc ( k Select user mapping, the map that is loaded by the utility 

mapscrn(8). 

esc ) Start sequencedefining GÌ (followed by oneof b, e, u, k, as 

above). 

esc > decpnm Set numeric keypad mode 

esc = decpam Set application keypad mode. 

esc ] ose (Should be: Operating system command) esc ] p nrrggbb: 

set palette, with parameter given in 7 hexadecimal digits 
after the final p : ■(. H eren is the color (0-16), and rrggbb 
indicates the red/green/blue values (0- 255). esc ] r: reset 
palette. 

ECMA-48 CSI SEQUENCES 

csi (or esc [) isfollowed by asequenceof parameters, at most npar(16), that are deci mal numbersseparated by semicolons. 
An empty or absent parameter istaken to beo. The sequenceof parameters may bepreceded by a single question mark. 

H owever, after csi [ (or esc [ [) a single character is read and thisentiresequenceisignored. (The idea isto ignorean 
echoed function key.) 

Theaction of acsi sequenceisdetermined by its final character. 



Character 



Function 



Description 



ICH 
CUU 
CUD 
CUF 
CUB 
CNL 
CPL 
CHA 
CUP 
ED 



IL 

DL 

DCH 

ECH 

HPR 

DA 

VPA 

VPR 

HVP 



Insert theindicated #of blank characters. 

M ovecursor up theindicated #of rows. 

M ovecursor down theindicated #of rows. 

M ovecursor righttheindicated #of columns. 

M ove cursorleft theindicated #of columns. 

M ovecursor down the indicated #of rows, to column 1. 

M ove cursorup theindicated #of rows, to column 1. 

M ovecursorto indicated column in current row. 

M ovecursorto theindicated row, column (origin at 1,1). 

E rase display (default: from cursor to end of display). 

esc [ 1 j: erase from start to cursor. 

esc [ 2 j: erasewholedisplay. 

E rase li ne (default: from cursor to end of line). 

esc [ 1 k: erase from start of line to cursor. 

esc [ 2 k: erase whole line. 

Insert theindicated #of blank lines. 

Delete the indicated #of lines. 

Delete the indicated #of characterson thecurrent line. 

E rase the indicated #of characterson thecurrent line. 

M ovecursor righttheindicated #of columns. 

AnSWerESC [ ? 6 c: 'I am a VT102 1 . 

M ove cursor to the indicated row, current column. 
M ove cursor down theindicated #of rows. 
M ove cursor to the indicated row, column. 



continue 
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Character 



Function 



Description 



TBC 

SM 

RM 

SGR 

DSR 

DECLL 



DECSTBM 



HPA 



W ithout parameter: clear tab stop at the current position. 

esc [ 3 g: delete ali tab stops. 

Set mode 

Reset mode. 

Set attributes. 

Status report. 

Set keyboard LEDs. 

esc [ 0 q: clear ali LEDs 

esc [ 1 q: set Serali Lock LED 

esc [ 2 q: set N um Lock LED 

esc [ 3 q: set Caps Lock LED 

Set scrolling region; parameters are top and bottom row. 

Save cursor location. 

Restare cursor location. 

M ovecursorto indicated column in current row. 



ECMA-48 SET GRAPHICS RENDITION 

TheECM A-48 SGR sequenceEsc [ <parameters> m sets display attributes. Several attributes can be set in th esame 
sequence. 



Parameter 



Result 



a Reset ali attributes totheirdefaults. 

1 Setbold. 

2 Set half-bright (simulated with color on a color display). 

4 Set underscore (simulated with color on a color display). 

(The colors used to simulate dim or underline are set usi ng esc ] ....) 

5 Setblink. 

7 Set reverse video. 

ie Reset selected mapping, display control flag, and toggle meta flag. 

11 Sdect nuli mapping, set display control flag, reset toggle meta flag. 

12 Selectnull mapping, set display control flag, set toggle meta flag. (Thetoggle meta flag 
causesthehigh bit of a byte to betoggled before the mapping tabletranslation isdone.) 

21 Set normal intensity. (Thisisnotcompatiblewith ECMA-48.) 

22 Set normal intensity. 

24 U nderline off. 

25 B link off. 

27 Reverse video off. 

30 Set black foreground. 

31 Set red foreground. 

32 Set green foreground. 

33 Set brown foreground. 

34 Set blue foreground. 

35 Set magenta foreground. 
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Parameter 


Result 


36 


Set cyan foreground. 


37 


Set white foreground. 


38 


Set underscoreon, set default foreground color. 


39 


Set underscoreoff, set default foreground color. 


40 


Set black background. 


41 


Set red background. 


42 


Set green background. 


43 


Set brown background. 


44 


Set blue background. 


45 


Set magenta background. 


46 


Set cyan background. 


47 


Set white background. 


49 


Set default background color. 



ECMA-48 MODE SWITCHES 

esc [ 3 h deccrm (default off): Display control chars. 

esc [ 4 h decim (default off): Set insert mode. 

esc [ 20 h lf/nl (default off): Automatically follow echo of lf, vt, or FFwith cr. 

ECMA-48 STATI! S REPO RT CO M M AN D S 

esc [ 5 n Devicestatusreport(DSR): AnswerisEsc [ 0 n (Terminal OK). 

esc [ e n Cursor position report (CPR): Answer ìsesc [ y ; x r, wherex, y isthecursor 

location. 

DEC PRIVATE MODE(DECSET/DECRST) SEQUENCES 

Thesearenot described in ECMA-48. The Set M odesequencesarelisted; the Reset M odesequencesareobtained by 
replacingthefinal h by 1. 

esc [ ? 1 h decckm (default off): W hen set, the cursor keys send an esc 0 prefix, rather than 

ESC [. 

esc [ ? 3 h deccolm (default off =80 columns): 80/132 col modeswitch. Thedriver sources note 

that this alone does not suffice; some user-mode uti lity such as resizecons(8) has to 
change the hardware registerson the console video card. 

esc [ ? 5 h decscnm (default off): Set reverse-video mode. 

esc [ ? 6 h decom (default off): W hen set, cursor addressing is relative to the upper left corner of 

thescrolling region. 

esc [ ? 7 h DECAWM(default on): Set autowrap on. In thismode, a graphics character emitted after 

column 80 (orcolumn 132 of deccolm ison) forcesawrap to thebeginningof the 
following linefirst. 

esc [ ? 8 h decarm (default on): Set keyboard autorepreat on. 

esc [ ? 9 h X10 M ouseReporting (default off): Set reporting modeto 1 (or reset to 0). 

(See "M ouseTracking.") 
esc [ ? 25 h deccm (default on): M akecursorvisible. 

esc [ ? 1000 h xn M ouseReporting (default off): Set reporting modeto 2 (or reset to 0). 

(See "M ouseTracking.") 
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LINUX CONSOLE PRIVATE CSI SEQUENCES 

Thefollowing sequences areneitherECM A-48 nor nati ve VT 102. They are nati veto the Linux console driver. Colorsarein 
SGR parameters: 0 = black, 1 =red, 2 = green, 3 =brown, 4 = blue, 5 = magenta, 6 =cyan, 7 =white. 



ESC 


1 ; n ] 


Set color n as the underli ne color 


ESC 


2 ; n ] 


Set color n asthedim color 


ESC 


8 ] 


M akethecurrent color pair the default attributes 


ESC 


9 1 n ] 


Set screen blank time-out to n minutes 


ESC 


10 ; n ] 


Set beli frequency in Hz 


ESC 


11 ; n ] 


Set beli durati on in msec 


ESC 


12 ; n ] 


Bringspecified consoleto thefront 


ESC 


13 ] 


U nblank the screen 


ESC 


14 ] 


Set the VE SA powerdown interval 



CHARACTERSETS 

Thekernelknowsaboutfour tran s! ati 0 n s of bytes i nto con so I e-screen sym bo I s. T h e f ou r tabi es are 

■ Latini to PC 

■ VTlOOgraphicstoPC 

■ PC to PC 

■ User-defined 

Therearetwo character sets, called GO and GÌ, and oneof them isthecurrent character set. (Initially GO.) Typing " n causes 
G 1 to become current, ■ 0 causes G 0 to become current. 

ThesevariablesGo and gì pointto atranslation table, and can bechanged by the user. Initially, they poi nt at the first two 
tables, Latini to PC and VT100 graphicsto PC, respectively. The sequences esc ( Band esc ( 0 and esc ( uandEsc ( k 
cause G0 to poi nt at the first, second, third, and fourth translati on tables in the precedi ng list, respectively. The sequences esc 
) Band esc ) 0 and esc ) u and esc ) k caused to poi ntat the first, second, third, and fourth translation tablesin the 
precedi ng li st, respectively. 

ThesequenceEsc c causes a terminal reset, which iswhat you want if the screen isall garbled. Theoft-advised "echo "v"o" 
will only makeGO current, butthereisno guaranteethatG0 poi ntsat the first table. In some distri butionsthereis a program 
reset(l) that just doesecho "[c. If your terminf o entry for the console is correct (and hasan entry rsi=c), then tput reset 
will also work. 

The user-defined mapping table can beset usi ng mapscrn(8).Theresult of themapping isthat if a symbol c isprinted, the 
symbol s = map[c] issentto the video memory. The bitmap that correspondstos isfound in the character rom, and can be 
changed usi ng setfont(8). 

MOUSE TRACKING 

The mouse tracking faci lity isintended to return xterm-compatible mouse status reports. Because the console driver hasno 
wayto know the devi ce or typeof the mouse, these reports are returned in the console input stream only when thevirtual 
terminal driver receives a mouse update ioctl. These ioctls must begenerated by a mouse-aware user-mode application such 
asthegpm(8) daemon. 

Parameters for ali mouse tracking escape sequences generated byxte™ encodenumeric parametersin a si ngle character as 
vaiue+040. Forexample, ! isl. Thescreen coordinate system isl-based. 

Thexi0 compatibility modesendsan escape sequenceon button press encoding the location and the mouse button pressed. 
It isenabled by sending esc [ ? 9 h and disabled with esc [ ? 9 ì.Onbutton press, xte™ sendsEsc [ m bxy (sixcharac- 
ters). H ereb is button 1, and x and y are the x and y coordinatesof the mouse when the button was pressed. Thisisthesame 
code the kernel also produces. 



console codes 
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Normal tracking mode(not implemented in Linux2.0.24) sendsan escape sequenceon both button press and release. 
M odifier i nformation isalsosent. Itisenabled bysendingEsc [ ? 1000 h and disabled with esc [ 1000 1. 0 n button press 
or release, xterm sends esc [ m bxy. T he low two bitsofb encode button information: 0=M Bl pressed, 1=M B2 pressed, 
2=M B3 pressed, 3=release. The upper bits encode what modifiersweredown when the button was pressed and areadded 
together: 4=Shift, 8=M età, 16=C ontrol. Again, x and y are the x and y coordinatesof the mouse event. Theupper-left corner 
is(l,l). 

COMPARISONS WITH OTHER TERMINALS 

M any different terminal typesaredescribed, li ke the Linux console, asbeingVTlOO-compatible. Herewediscussdifferences 
between the Linux console and the two most important others, theD EC VT102 and xterm(l). 

CONTRO L-CHARACTER HANDLING 

Thevti02 also recognized thefollowing control characters: 
nul (0x00) was ignored. 
enq (0x05) triggered an answerback message. 
dci(0xii, "q, xon) resumed transmission. 

dc3 (0x13, "s, xoff) caused vti00 to ignore(and stop transmitting) ali codes except xoff and xon. 
vTiao-like dci /DC3 processing may beenabled by thetty driver. 

The xterm program (in vtioo mode) recognizes the control characters bel, bs, ht, lf, vt, ff, cr, so, si, esc. 
ESCAPE SEQUEN CES 

Thefollowing VT100 console sequences are not implemented on the Linux console: 
E9:apeSequence Function D escription 

esc n ss2 Single shift 2. (Select G2 character set for the next 

character only.) 

esco ss3 Single shift 3. (5elect G3 character set for the next 

character only.) 

esc p dcs D evice control stri ng(ended by esc \). 

esc x sos Start of stri ng. 

esc" pm Privacy message (ended byEsc\). 

esc \ st String terminator. 

esc*... DesignateG 2 character set. 

esc + . . . DesignateG 3 character set. 

The program xterm (in vti00 mode) recognizes esc c, esc # 8, esc >, esc =, esc d, esc e, esc h, esc m, esc n, esc 0, esc p 
... esc esc z (it answers esc [ ? 1 ; 2 c, "I am a vtlOO with advanced video option") and esc "... esc with the same 
meaningsas indicated above. It acceptSEsc (, esc ), esc *, esc + followed by 0, a, b for theDEc special character and line 
drawingset, uk, and usascii, respectively. 1 1 accepts esc ] for the setti ng of certain resources: 

esc ] 0 ; txt bel Set icon name and window title to txt. 

esc ]1 ; txt bel Set icon name to txt. 

esc ] 2 ; txt bel Set window title to txt. 

esc ] 4 6 ; name bel C hange log fi le to name (normally disabled by a compi le-time option). 

ESC ] 5 0 ; f n BEL Set font tO f n. 

It recognizesthefollowing with slightiy modified meaning: 
esc 7 decsc Savecursor 
esc 8 decrc Restore cursor 
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It also recognizes 

ESC F 
ESC 1 
ESC m 

ESC n LS2 
ESC o LS3 
ESC j LS3R 

ESC g LS2R 

ESC " LS1R 

It does not recognize esc \ ... 
CSISEQUENCES 

Thexterm program (asof xFree86 3.1.2G) does not recognize the blink or invisible-modeSGRs. Stock X11R6 versionsdo 
not recognize the color-setting SGRs. Ali other ECM A-48 csi sequencesrecognized by Linux are also recognized by xterm, 
and viceversa. 

Thexterm program will recognize ali of theD EC Private M ode sequenceslisted earlier, but none of the Linux private-mode 
sequences. For discussi on ofxterm'sown private-mode sequences, referto the Xterm Control Sequencesdocument by Edward 
M oy and Stephen Gildea, availablewith thex distri bution. 

BUGS 

In 2.0.23, csi isbroken, and nul isnot ignored inside escape sequences. 
SEE ALSO 

console(4), console_ioctl(4), charsets(4) 

Linux, 31 October 1996 

console ioctls 

consoie ioctis— Ioctls for console termi nal and virtual consoles 
DESCRIPTION 

Thefollowing Linux-peculiar iocti() requestsaresupported. Each requiresathird argument, assumed hereto beargp. 



WARNING 



If you use thefollowing information, you aregoingto bum yourself. Ioctls are undocumented Linux internals, liableto 
bechanged withoutwarning. UsePOSIX functions. 



C ursor to lower-left corner of screen (if enabled by the 

hpLowerleftBugCompat resource). 

M emory lock (per H P termi nals). Locksmemory abovethe 
cursor. 

M emory unlock (per H P terminals). 
I nvoke the G 2 character set. 
I nvoke the G 3 character set. 
I nvoke the G 3 character set asGR. 
H as no visibleeffect in xterm. 
I nvoke the G 2 character set asGR. 
H as no visibleeffect in xterm. 
I nvoke the G 1 character set as gr. 
H as no visibleeffect in xterm. 
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G et state of LED s. argp pointsto a long int. Thelower threebitsof *argp are set to 

thestateof theLEDs, asfollows: 

led_cap 0x04 capsIockLED 

lec_num 0x02 numlockLED 

led_scr 0x01 serali lock LED 

Set theLEDs. The LED sare setto correspond to thelowerthree bitsof argp. 
H owever, if a higher order bit is set, theLEDsrevert to normal, displaying the state 
of thekeyboard functionsof caps lock, num lock, and serali lock. 
Before 1.1.54, theLEDs just reflected thestateof thecorresponding keyboard flags, 
and kdgetled/kdsetled would also change the keyboard flags. Si nce 1.1.54 theLEDs 
can bemadeto display arbitrary information, but by default they display the 
keyboard flags. The followingtwo ioctlsareused to access the keyboard flags. 
Get keyboard flags capsLock, NumLock, scroiiuck (not lights). argp pointsto achar 
that is set to theflag state. The low order threebits(mask 0x7) get thecurrent flag 
state, and the low order bitsof thenext nibble(mask0x70) get the default flag state 
(since 1.1.54). 

Set keyboard flags capsLock, NumLock, scroiiuck (not lights). argp hasthe desired 
flag state. The low order three bits (mask 0x7) have the flag state, and the low order 
bits of the next ni bble (mask 0x70) have the default flag state (since 1.1.54). 
Get keyboard type. This returnsthevalueKB 101, defined as0x02. 
Add I/O portasvalid. Equivalenti) ioperm(arg,i,i). 
D elete I/O portasvalid. Equivalentto ioperm(arg,i ,0). 
Enablel/O to video board. Equivalentto ioperm(0x3b4, Ox3df-0x3b4+i, 1). 
D isable I/O to video board. Equivalentto ioperm(0x3b4, 0x3df-0x3b4+ 1, 0). 
Set text/ graphics mode, argp isoneof these: 

KD_TEXT 0X00 
KDGRAPHICS 0X01 

Get text/graphics mode, argp pointsto a long which is set to oneof theabovevalues. 
Generate toneof specified length. Thelower 16 bitsof argp specify theperiod in 
clock cycles, and tneupper 16 bitsgivetheduration in msec. I f the duration iszero, 
thesound isturned off. Control returnsimmediately. Forexample, argp = (125«16) 
+ 0x637 would specify the beep normally associated with actn-G. 
Start or stop sound generation. Thelower 16 bitsof argp specify theperiod in clock 
cycles (that is, argp =1193180/frequency). argp = 0 turns sound off. In either case, 
control returnsimmediately. 

Get thecurrent default color map from kernel, argp pointsto a 48-bytearray. 
(Since 1.3.3.) 

Change the default text-mode color map. argp pointsto a48-bytearray that 
contains, in order, thered, green, and bluevaluesforthel6 available screen colors 0 
isoff, and 255 isfull intensity. Thedefault colors are, in order: black, dark red, dark 
green, brown, dark blue, dark purple, dark cyan, lightgrey, dark grey, bright red, 
bright green, yellow, bright blue, bright purple, bright cyan, and white. (Since 
1.3.3.) 

Gets256-character screen font in expanded form. argp pointsto an 8192-bytearray. 
Fai Is with errar codeEiwAL if thecurrently loaded font is a 512-character font, or if 
the console is not in text mode. 



Getsscreen font and associateci information. argp pointsto astruct consoiefontdesc 
(seepio_FONTx). On cali, thecharcount field should beset to the maximum number 
of charactersthatwould fit in the buffer poi nted to by chardata. 0 n return, the 
charcount and charheight are fi Ned with the respecti ve data for the currently loaded 
font, and the chardata array contai ns the font data if the ini ti al valueof charcount 
indicateci enough space wasavai labi e; otherwise the buffer isuntouched and errno is 
setto enomem. (Since 1.3.1.) 

Sets256-characterscreen font. Loadfontinto the EGA/VGA character generato r. 
argp pointsto a 8192-byte map, with 32 bytes per character. Only first n ofthem are 
usedforan 8xNfont(0 < n <= 32). T his cai I also invalidates the U nicode mapping. 
Setsscreen font and associ ated rendering information. argp pointsto a 

struct consoiefontdesc { 

u_short charcount; /* characters in font 

(256 or 512) */ 
u_short charheight; /* scan lines per 

character (1-32) */ 
char "chardata; /* font data in 

expanded forni */ 

}; 

If necessary, thescreen will be appropri ately resized, and sigwinch sent to the 
appropriate processes. Thiscall also invalidates theUnicode mapping. (Since 1.3.1.) 
Resets thescreen font, size, and U nicode mapping to thebootup defaults. argp is 
unused, but should be setto Nuu_to ensure compati bility with future versi onsof 
Linux. (Since 1.3.28.) 

Getscreen mapping from kernel, argp pointsto an area of size e_tabsz, which is 
loaded with the font positi onsused to display each character. Thiscall islikely to 
return useless information if the currently loaded font ismorethan 256 characters. 
G et full U nicode screen mapping from kernel, argp pointsto an area of size 
E_TABsz*sizeof (unsigned short), which isloaded with theU nicodeseach character 
represent. A special set of U nicodes, starti ngat u+Foae, areused to represent "direct 
to font" mappings. (Since 1.3.1.) 

Loads the user-defi nable (fourth) tablein the kernel that maps bytes into console 
screen symbols. argp pointsto an area of sizeE_TABsz. 

Loads the user-defi nable (fourth) tablein the kernel that maps bytes into U nicodes, 
which arethen translated into screen symbols accordi ngto thecurrently loaded 
Unicode-to-font map. Special U nicodes starting at 11+F000 can beused to map 
di rectly to thefont symbols. (Since 1.3.1.) 
Get U nicode-to-font mapping from kernel, argp pointsto a 

struct unimapdesc { 
u_short entryct; 
struct unipair *ent r i es ; 

>; 

where entri es points to an array of 
struct unipair { 
u_short unicode; 
u_short fontpos; 

>; 

(Since 1 .1 .92. ) 

PutU nicode-to-font mapping in kernel, argp pointsto a struct unimapdesc. 
(Since 1.1.92.) 
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Cleartable, possi blyadvi se hash algorithm. argp pointsto a 

struct unimapinit { 

u short advised hashsize; /* 0 if no opinion */ 
u short advised hashstep; /* 0 if no opinion */ 
u short advised hashlevel; /* 0 if no opinion */ 

>; 

(Sirice 1.1.92.) 

Getscurrent keyboard mode, argp pointsto a long, which isset to oneof these: 

K_RAW 0X00 
K_XLATE 0X01 
K_MEDIUMRAW 0X02 
KJJNICODE 0X03 

Sets current keyboard mode, argp isa long equal to oneof the above vai ues. 
Gets meta key handling mode, argp pointsto a long which isset to oneof these: 
k_metabit 0x03 Set high order bit 

k_escprefix 0x04 Escapeprefix 

Sets meta key handling mode argp isa long equal to oneof the precedi ngvalues. 
Gets one entry in key translati on table(keycodeto action code), argp pointsto a 

struct kbentry { 
u_char kb_table; 
u_char kb_index; 
u_short kb_value; 

>; 

with thefirsttwo members filled in: kb tabie sei ects the key table (0 <= kb_tabie 

<MAX_NR_KEYMAPS), and kb_index isthe keyCOde (0 <= kb index <NR_KEYS). kb_value ÌS 

setto the corresponding action code, or k_hole if thereisnosuch key, or k_nosuchmap 
if kb_table isinvalid. 

Sets one entry in translation table. argp pointsto astruct kbentry. 
Gets one function key string. argp pointsto a 

struct kbsentry { 
u_char kb_func; 
u_char kb__string[512] ; 

kb_string isset to the (NULL-termi nated) string corresponding to thekb_functh 
function key action code. 

Sets one function key string entry, argp pointsto astruct kbsentry. 
Read kernel accent table. argp pointsto a 

struct kbdiacrs { 

unsigned int kb_cnt; 

struct kbdiacr kbdiacr[256] ; 

>; 

wherekb cnt isthe numberof entri es in thearray, each of which isa 

struct kbdiacr {u_char diacr, base, result ;}; 

Read kernel keycode table entry (scan codeto keycode). argp pointsto a 

struct kbkeycode {unsigned int scancode, keycode; }; 

keycode isset to correspond to the given scancode.(89<=scancode <= 255 only. 

Fori <= scancode <= 88, keycode==scancode.) (Since 1.1.63.) 

Write kernel keycode tabi e entry, argp pointsto struct kbkeycode. (Since 1.1.63.) 
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KDSIGACCEPT 



VT OPENQRY 



VT GETMODE 



VT^SETMODE 
VT GETSTATE 



VT_RELDISP 
VT_ACTIVATE 
VT_WAITACTIVE 
VT_DISALLOCATE 
VT RESIZE 



VT RESIZEX 



The cali ing process indicates its willingnessto accept the signal argp when it is 
generateci by pressing an appropriate key combinati on. (1 <= argp <=nsig). 

(See spawn_console() in linux/drivers/char/keyboard .c. ) 

Returnsthefirst available (nonopened) console, argp pointsto an int thatis setto 
thenumber of thevt (1 <= *argp <=max_nr_consoles). 
Get modeof activevt. argp pointsto a 

struct vt mode { 
char mode; /"vtmode*/ 

char waitv; /* if set, hang on writes if not active */ 
short relsig; /* signal to raise on release reg */ 
short acqsig; /* signal to raise on acquisition */ 
short frsig; /* unused (set to 0) */ 

}; 

mode issetto one of thesevalues: 
vt_auto Auto vt switching 

vt_process Processcontrolsswitching 
vt_ackacq Acknowledgeswitch 

Set modeof activevt. argp pointsto a struct vtjnode. 

Getglobal vt state info, argp pointsto a 

struct vt_stat { 

ushort v_active; /* active vt */ 
ushort v_signal; /*signalto send*/ 
ushort v_state;/*vtbitmask*/ 

>; 

Foreach vt in use, thecorresponding bit in the v state mem ber is set. (Kernelsl.O 
through 1.1.92.) 
Release a display. 

SwitCh tO vt argp (1 <= argp <=MAX_NR_C0NS0LES). 

Waituntil vt argp hasbeen activated. 

Deallocate the memory associ ated with vt argp. (Since 1.1.54.) 

Set the kernel's idea of screensize argp pointsto a 

struct vt_sizes { 

ushort v_rows; /*#rows*/ 

ushort v_cols ; /*#columns */ 

ushort v_scrollsize; /* no longer used */ 

>; 

Notethatthisdoesnot change the video mode See resizecons(8). (Since 1.1.54.) 

Set the kernel's idea of variousscreen parameters. argp pointsto a 

struct vt_consize{ 

ushort v_rows; /* number of rows*/ 

ushort v_cols; /* number of columns*/ 

ushort v_vlin; /* number of pixel rowson screen */ 

ushort v_clin; /* number of pixel rows per character*/ 

ushort v_vcol; /* number of pixel columns on screen */ 

ushort v_ccol; /* number of pixel columns per character */ 

}; 

Any parameter may beset to zero, indicati ng no change, but if multiple parameters 
are set, they must beself-consistent. N otethatthisdoes not change the video mode 
See resizecons(8). (Since 1.3.3.) 
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The action of thefollowing 
These are legai only for the 

TIOCLINUX, subcode=0 

TIOCLINUX, subcode=1 
TIOCLINUX, subcode=2 



TIOCLINUX, subcode=3 
TIOCLINUX, subcode=4 
TIOCLINUX, subcode=5 

TIOCLINUX, subcode=6 

TIOCLINUX, subcode=7 

TIOCLINUX, subcode=8 

TIOCLINUX, subcode=9 

TIOCLINUX, subcode=10 



ioctlsdependson the first byte in thestruct pointed to by argp, referred to hereas the subcode, 
superuser or the owner of the current tty. 

Dump thescreen. D isappeared in 1.1.92. (With kernel 1.1.92 or later, read from 

/dev/vcsN or /dev/vcsaN instead.) 

Gettask information. D isappeared in 1.1.92. 

Set selection. argp pointsto a 

struct{fchar subcode short xs, ys, xe, ye; short sel_mode; } 

xs and ys are the starti ngcolumn and row. xe and ye aretheending column and 
row. (Upper-left corner isrow=coiumn=i.) seijnode is 0 for character-by-character 
selection, 1 forword-by-word selection, or2 for li ne-by-li ne selection. Theindicated 
screen characters are highlighted and saved in the static array sei buffer in devices/ 

char/console . c. 

Paste selection. The characters in the selection buffer arewritten tofd. 
Unblank thescreen. 

Sets contents of a 256- bit look up table defining characters in a "word", for word- 
by-word selection. (Since 1.1.32.) 

argp pointsto a char that is set to the value of the kernel vari able shift state. (Since 
1.1.32.) 

argp pointsto a char that issetto thevalueof the kernel vari able report mouse. 
(Sincel.1.33.) 

Dump screen width and height, cursor position, and ali thecharacter-attribute pairs. 
(Kernels 1.1.67 through 1.1.91 only. W ith kernel 1.1.92 or later, read from /dev/ 
vcsa* instead.) 

Restare screen width and height, cursor position, and ali thecharacter-attribute 
pairs. (Kernels 1.1.67 through 1.1.91 only. W ith kernel 1.1.92 or later, writeto 
/dev/vcsa* instead.) 

H andles the power savi ngfeature of thenew generation of moni tors. VESA screen 
blanking mode is set to argp[l], which governswhat screen blanking does: 

0 Screen blanking isdisabled. 

1 The current video adapter regi ster setti ngs are saved, then the 
controller isprogrammed to turn off the vertical synchronization 
pulses. This puts the monitor into standby mode If your monitor has 
an Off_M ode timer, then it will eventually power down by itself. 

2 Thecurrent settings are saved, then both the vertical and horizontal 
synchronization pulses are turned off. This puts the monitor into off 
mode. If your monitor has no Off_M ode timer, or if you wantyour 
monitor to power down immediately when the blank timer ti mesout, 
then you choosethisoption. (Caution: Poweringdown frequently 
will damage the monitor.) (Since 1.1.76.) 



RETURN VALUES 

-1 for errar, and ermo isset. 

ERRORS 

ermo may take on these values: 

EBADF 
ENOTTY 



Filedescriptor is invalici. 

Filedescriptor is not associated with acharacter special device, or the speci fi ed 
request does not apply to it. 
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einval File descri ptor or argp isinvalid. 

eperm Permission violation. 



WARNING 



Do not regard thisman pageasdocumentation of the Linux console ioctls. This isprovided for thecuriousonly, asan 
alternative to readingthesource. Ioctls are undocumented Linux internals, liableto bechanged withoutwarning. (And 
indeed, this page more or less descri bes the si tuation asof kernel version 1.1.94; there are many minor and not-so-minor 
differences with earlier versions.) 

Very often, ioctls are introduced for communication between the kernel and oneparticularwell-known program (fdisk, 
hdparm, setserìai, tuneip, ioadkeys, seiection, setfont, and so on), and their behavior will bechanged when required by 
this parti cui ar program. 

Programs usi ngthese ioctls will not beportableto other versions ofU N IX, will notworkon older versions of Linux, and 
will notwork on future versi onsof Linux. 
UsePOSIX functions 



SEEALSO 

kbd jnode(l), loadkeys(l), dumpkeys(l), mknod(l), setleds(l), setmetamode(l), ioperm(2), termios(2), execve(2), fcntl(2), 
charsets(4), console(4), console_codes(4), mt(4), sd(4), tty(4), ttys(4), vcs(4), vcsa(4), mapscrn(8), setfont(8), resizecons(8), 
/ usr/ include/ linux / kd. h, /usr /include/ linux/ vt . h. 

Linux, 18 September 1995 



fd 

fd— Floppy disk device 
CONFIGLI RATIO N 

Floppy drives are block devi ces with major number 2. Typically, they areowned by root. floppy (that is, user root, group 
floppy) and haveeither modeoeeo (access checking vi a group membership) or modeo666 (everybody has access). The minor 
numbersencode the device type, drive number, and controller number. For each devi ce type (that is, combination of densi ty 
and track count), there is a base minor number. To this base number, add thedrive's number on its controller and 128 if the 
driveison thesecondary controller. In thefollowing device tables, n represents the drive number. 



WARNING 



If you use formats with moretracksthan supported byyour drive you may cause itmechanical damageTryingonceif 
more tracks than the usuai 40/80 are supported should not damage it, but no warranty is gi ven for that. D on't create 
device entries for those formats to prevent their usageif you are not sure. 




D rive-i ndependent de/ice fi lesthat automati cally detect the media format and capacity are 
Name Base minor* 

fdn 0 

5.25-inch doublé density devicefiles: 



N ame 


C apac. 


Cyl. 


Sect. 


Heads 


Base minor # 


fdnd360 


360K 


41) 


y 


-) 
z 


4 


5.25-inch high density devicefiles: 










N ame 


Capac. 


Cyl. 


Sect. 


Heads 


Base minor # 


fdnti360 


360K 


40 


9 


2 


20 


fdnh410 


410K 


41 


10 


2 


48 


fdnh420 


420K 


4Z 


i n 
1U 


l 


64 


fdnh720 


720K 


on 
SU 


a 


l 


24 


fdnh880 


880K 


on 

80 


il 


i 


88 


fdnh1200 


1200K 


on 
80 


lb 


i 


8 


fdnh1440 


1440 K 


80 


18 


2 


40 


fdnh1476 


1476K 


82 


18 


2 


56 


fdnh1494 


1494K 


83 


18 


2 


72 


fdnh1600 


1600K 


80 


20 


2 


92 


3.5-inch doubledensity devicefiles: 










N ame 


C apac. 


Cyl. 


Sect. 


H eads 


Base minor # 


fdnD368 


360K 


on 


y 


i 


12 


fdnD720 


720K 


on 
oU 


y 


Z 


16 


fdnD800 


800K 


on 
oU 


1U 


z 


120 


fdnD1040 


1040K 


on 
oU 




~l 

z 


84 


fdnD1120 


1120K 


on 
oU 


1 A 

14 


z 


88 


3.5-i neh high density devicefiles: 










N ame 


Capac. 


cyl. 


C rv+ 

bea. 


U urie 

n eaas 


Base minor # 


fdnH360 


360K 


40 


9 


2 


12 


fdnH720 


720K 


80 


9 


2 


16 


fdnH820 


820K 


82 


10 


2 


52 


fdnH830 


830K 


83 


10 


2 


68 


fdnH1440 


1440 K 


80 


18 


2 


28 


fdnH1600 


1600K 


80 


20 


2 


124 


fdnH1680 


1680K 


80 


21 


2 


44 


fdnH1722 


1722K 


82 


21 


2 


60 


fdnH1743 


1743K 


83 


21 


2 


76 


fdnH1760 


1760K 


80 


22 


2 


96 


fdnH1840 


1840K 


80 


23 


2 


116 


fdnH1920 


1920K 


80 


24 


2 


100 
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3.5-i neh extra density devi ce files: 



Name Capac. Cyl. Sect. Heads Base minor* 

fdnE2880 2880K 80 36 2 32 

fdnCompaQ 2880K 80 36 2 36 

fdnE3200 3200K 80 40 2 104 

fdnE3520 3520K 80 44 2 108 

fdnE3840 3840K 80 48 2 112 



DESCRIVO N 

fd special files access thefloppy disk drivesin raw mode. The following iocti(2) calls are supported by fd devices: 
fdclrprm clearsthe media informati on of a drive (geometryof disk in drive). 

fdsetprm sets the media informati on of a drive. The media informati on will belostwhen the media ischanged. 

fddefprm sets the media i nformati on of adrive(geometry of disk in drive). The media information will not belostwhen the 

media ischanged. Thiswill disable autodetection. In orderto re-enable autodetection, you haveto issuean fdclrprm. 

fdgetdrvtyp displays the type of a drive (name parameter). Forformatsthatwork in several drive types, fdgetdrvtyp returnsa 

namethat is appropriate for the oldest drive type that supportsthis format. 

fdflush invalidates the buffer cachefor the given drive 

fdflush invalidates the buffer cachefor the given drive. 

fdsetmaxerrs sets the errar thresholds for reporti ngerrors, aborti ng the operati on, recai ibrating, resetting, and readingsector 
by sector. 

fdsetmaxerrs gets the current errar thresholds. 
fdgetdrvtyp gets the internai name of the drive. 
fdwerrorclr clears the write errar statistics. 

fdwerrorget reads the write error statistics. T hese include the total number of write errors, thelocation and disk of thefirst 
write errar, and thelocation and disk of the last write error. D isks are identified by a generation number that is incremented 
at(almost) each disk change. 

fdtwaddle switches the dri ve motor off for a few microseconds. Thismight beneeded in orderto access a disk whosesectors 

aretoo closetogether. 

fdsetdrvprm sets various drive parameters. 

fdgetdrvprm reads these parameters back. 

fdgetdrvstat gets the cached dri ve state (disk changed, write protected et al.) 

fdpolldrvstat poi Is the dri ve and return its state. 

fdgetfdcstat gets the floppy controller state. 

fdreset resets the floppy controller under certain conditions. 

fdrawcmd sendsa raw command to thefloppy controller. 

For more precise information, consult also the<nnux/fd.h> and <linux/fdreg.h>include files, aswell asthemanual page for 
floppy control. 

NOTES 

The vari ousformats ali ow you to read and write many types ofdisks. H owever, if a floppy isformatted with atoo small 
intersector gap, performance may drop, up to needingafew secondsto access an entire track. To prevent this, useinterleaved 
formats. It isnot possibleto read floppies that areformatted using GCR (group code recordi ng), which isused by Apple II 
and M acintosh computers(800K disks). Reading floppies that are hard sectored (onehole per sector, with the index hole 
bé ng a little skewed) isnot supported. This used to be common with older 8-inch floppies. 



FILES 

/dev/fd* 

AUTHORS 

Alain Knaff (Aiain.Knaff@imag.fr), David Niemi (niemidc@clark.net), Bill Broadhurst (bbroad@netcom.com). 
SEEALSO 

floppycontrol(l), mknod(l), chown(l), getfdprm(l), superf ormat(l), mount(8), setfd-prm(8) 
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hd 

hd-M FM /ID E hard disk device 
DESCRIPTION 

hd* are block devi cesto access M FM/ID E hard disk drivesin raw mode. The master drive on the primary I D E controller 
(major device num ber 3) ishda; the slave drive isndb. The master drive of the second controller (major device number 22) is 
hdc and the slave hdd. 

General IDE block device names havetheform hdx , or ndxp, wherex isa letter denoti ng the physical drive, and p isa 
number denoti ng the parti ti on on that physical drive. The first form, hdx, isused to address the whole drive. Partition 
numbers are assi gned in the order the partiti ons are discovered, and only nonempty, nonextended partitionsget a number. 
H owever, partition numbers 1-4 aregiven to thefour partiti ons described in the M BR (the primary parti ti ons), regardlessof 
whether they areunused or extended. Thus, the first logicai partition will betidxs. Both DOS-type partiti oning and BSD- 
disk label partitioning are supported. You can haveat most63 partitionson an ID E disk. 

Forexample, /dev/hda refersto ali of the first ID E drive in the system; and /dev/hdb3 refersto thethird DOS primary 
partition on the second one 

They are typically created by thefollowing: 

mknod -m 660 /dev/hda b 3 0 
mknod -m 660 /dev/hda1 b 3 1 
mknod -m 660 /dev/hda2 b 3 2 



mknod -m 660 /dev/hda8 b 3 8 

mknod -m 660 /dev/hdb b 3 64 

mknod -m 660 /dev/hdb1 b 3 65 

mknod -m 660 /dev/hdb2 b 3 66 



mknod -m 660 /dev/hdb8 b 3 72 
chown root.disk /dev/hd* 

FILES 

/dev/hd* 

SEEALSO 

mknod(l), chown(l), mount(8), sd(4) 
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ispell 

ispeii— Format of ispeii dictionariesand affix files 
D ESC RIPTIO N 

ispeii(l) requires two filesto define the languagethatit is speli checking. The first file is a dictionary contai ningwordsfor 
thelanguage, and thesecond isan affix filethat defines hemeaningof special flags in the dictionary. The two files are 
compi ned Py buiidhash (seespeii(l)) and written to a hash filethat isnot descriPed here. 

A raw ìspeii dictionary (either the main dictionary or your own personal dictionary) contains a list of words, oneper line. 
Each word may optional ly Pefollowed Py a slash (/) and oneor more flags, which modify the root word as explained later. 
D ependi ng on the opti onswith which ispeii wasbuilt, case may or may not besignificant in either the root word or the 
flags, independently. Specifi cally, if the compi le-ti me option capitalization isdefined, caseissignificant in the root word; if 
not, caseisignored in therootword. If the compile-time option maskbits is set to avalueof 32, caseisignored in theflags; 
otherwise, caseissignificant in theflags. Contact your system administrator or ispeii maintainer for moreinformation (or 
use the -w flag to find out). The dictionary should Pesorted with the-f flag of sort(l) Pefore the hash fileisPuilt; thisis 
doneautomatically by unchiist(l), which isthenormal way of building dictionaries. 

If the dictionary contains words that have stringcharacters (see the affix filedocumentation, following), they must be 
written in theformat given Py thedefstnngtype statement in the affix file. Thiswill bethecasefor most non-E nglish 
languages. Becareful to use this format, ratherthan that of your favorite formatter, when adding words to a dictionary. If 
you add words to your personal dictionary duri ng an ispeii sessi on, they wi II automati cally Peconverted to thecorrect 
format. This featu re can Peused to convert an enti re dictionary if necessary: 

echo qqqqq > dummy.dict 

buiidhash dummy.dict affix-file dummy.hash 

awk 'fprint " *"gENDfprint "#"g' old-dict-f ile \ 

! ispell -a -T old-dict-string-type \ 

-d ./dummy.hash -p . /new-dict -f ile \ 

> /dev/hull 

rm dummy.* 

T he case of therootword controis the case of words accepted Py ispeii, asfollows: 

1. If therootword appearsonly in lowercase(forexample, Pop), itwill Pe accepted in lowercase, capitalized, orali capitals. 

2. If therootword appears capitalized (forexample, RoPert), itwill not Pe accepted in ali lowercase, Putwill Pe accepted 
capitalized orali in capitals. 

3. If therootword appears ali in capitals (forexample, U N IX), itwill only Pe accepted ali in capitals. 

4. If therootword appears with a "funny" capitalization (forexample, ITCorp), a word will Pe accepted only if it follows 
that capitalization, or if it appears ali in capitals. 

5. M orethan one capitalization of a root word may appear in the dictionary. Flags from different capital izations are 
comPined usingoR. 

Redundant capitalizations (for example, Pop and Bop) will Pe comPined Py buiidhash and by ispeii (for personal dictionar- 
ies), and can Pe removed from a raw dictionary Py munchiist. 

Forexample, the dictionary 

bob 

Robert 
UNIX 
ITcorp 
ITCorp 

will accept bob, Bob, bob, Robert, Robert, unix, iTcorp, ncorp, and itcorp, and will rej ect ali others. Some of the unacceptaPle 
formsarebob, robert, Unix, and ItCorp. 




As mentioned, root wordsin any dictionary may beextended by flags. Each flag is a si ngle alphabetic character, which 
representsa prefixor suffixthat may beadded to the root to forni anew word. For example, in an English dictionary the d 
flag can beadded to batheto makebathed. Because flags are represented as a single bit in thehashed dictionary, this results 
in significant space savi ngs. The munchiist script wi II reduce an existing raw dictionary by addi ng flags when possi ble. 

When a word isextended with an affix, theaffixwill beaccepted only if it appears in the same case as the initial (prefix) or 
final (suffix) letterof the word. Thus, for example, the entry unix/m in the mai n dictionary (M meansadd an apostropheand 
an sto make a possessive) would accept U N IX'S butwould reject UN IX's If UN IX'sis legai, it must appear as a separate 
dictionary entry, and it will not becombined by munchiist. (In general, you don't need to worry about these thi ngs; 
munchiist guarantees that its output dictionary will accept the same set ofwordsas its input, so ali you haveto do isadd 
wordsto the dictionary and occasionally run munchiist to reduce its si ze.) 

As mentioned, the affix defi ni tion file descri bes the affixes associateci with parti cui ar flags. It also describes the character set 
used by the language. 

Although the affi x-defi ni tion grammar isdesigned for a line-oriented layout, it isactually afree-formatgrammar and can be 
laid out weirdly if you want. Commentsarestarted by a pound (sharp) sign (#), and conti nueto the end of the li ne. 
Backslashesaresupported in the usuai fashion (\nnn, plus specials \n, \r, \t, w, \f, \b, and thenew hex format \xnn). Any 
character with special meaning to the parser can bechanged to an uninterpreted token by backslashing it; for example, you 
can declare a flag named asterisk or colon with flag n* : or flag n: :. 

The grammar will bepresented in a top-down fashion, with di scussi on of each element. An affix-definition file must contai n 
exactly onetable 

t abl e : [header s ] [pr ef i xes ] [s uf f i xes ] 

At least oneof prefixes and suffixes is required. They can appear in either order. 

hea d e r s : [opt i o n s ] c ha r ■ s et s 

T he headers descri beoptionsglobal to this dictionary and language. These include the character setsto beused and the 
formatter, and the defaultsfor certain ispell flags. 

opti o n s : {fmtr-stmt | o p t - s t mt J f I a g - s t mt j n u m- s t mt } 

T he opti onsstatements defi ne the defaultsfor certain ispeii flags and for the character setsused by theformatters. 

f mt r ■ s t mt : { nroff-stmt j t e x ■ s t mt } 

A fmtr-stmt statement describes characters that have special meaning to a formatter. N ormally, this statement is not 
necessary, but some languages may have preempted the usuai defaults for use as language-specific characters. I n this case, 
these statements may beused to redefinethespecial characters expected by the formatter. 

nroff-stmt : { nroffchars j troffchars } stri r g 

Thenroffcnars statement allowsredefinition of certain nroff control characters. The stri ng given must be exactly fi ve 
characters long, and must list substitutionsfor theleft and right parentheses, theperiod, the backslash, and the asterisk. (The 
right parenthesis is not currently used, but is included for compi eteness.) For example, thestatement: 

nroffchars {}.\\* 

would replace theleft and right parentheses with left and right curly bracesfor purposesof parsi ng nroff/troff stri ngs, with 
no effect on the others (admittedly a contrived example). N otethat the backslash isescaped with a backslash. 

tex-stmt : { TeXchars | texchars } stri n g 

TheTexchars statement allows redefinition of certain TeX/LaTeX control characters. The stri ng given must be exactly 
thirteen characters long, and must list substitutionsfor the left and right parentheses, the left and right square brackets, the 
left and right curly braces, theleft and right angle brackets, the backslash, the dollar sign, the asterisk, theperiod or dot, and 
the percent sign. For example, thestatement: 

texchars ( ) \ [ ]<\><\>\\$* .% 
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would replace thefunctions of the left and right curly braceswith theleft and right angle brackets for purposesof parsi ng 
TeX/LaTeX constructs, while retaining their functionsfor the t±b bibliographic preprocessor. N otethatthebackslash, the 
left square bracket, and the right angle bracket must be escaped with a backslash. 

o p t - s t mt : { c mp ri d - s t mt j a f f ■ s t mt } 
c mp n d - st mt : compoundwords compound- opt 

aff-stmt : allaffixes o n - or- off 

on-or-off : { on | off } 
compound- opt : { on-or-off ] controlied character } 

An opt-stmt, used in the precedi ng code, controis certain ispeii defaultsthat are best madelanguage-specific. The 
aiiaffixes statement controis the default for the -p and -m optionsto ispeii. If allaffixes isturned off (the default), ispeii 
will default to the behavior of the -p flag: root/affix suggestions will only be made if there are no "near misses." If allaffixes 
isturned on, ispeii will default to the behavior of the -m flag: root/affix suggestions will alwaysbemade. 

The compoundwords statement controis the default for the -b and -c optionsto ispeii. If compoundwords isturned off (the 
default), ispeii will default to the behavior of the-B flag: run-togetherwordswill bereported aserrors. If compoundwords is 
turned on, ispeii will default to the behavior of the-c flag: run-togetherwordswill beconsidered ascompoundsif both are 
in thedictionary. Thisisuseful for languagessuch asGerman and N orwegian, which form largenumbersof compound 
words. Finally, if compoundwords isset to controlied, only wordsmarked with theflag indicateci by character (which should 
not beotherwiseused) will beallowed to parti ci paté in compound formation. Becausethis option requirestheflagsto be 
specified in thedictionary, it isnot available from thecommand line. 

flag-stmt : f lagmarker c ha r a c t er 

Thefiagmarker statement describes the character that isused to separate affixflags from theroot word in a raw dictionary 
file. Thismust bea character that isnotfound in any word (includi ng in stringcharacters; seefollowing). The default is/ 
because this character is not normally used to represent special charactersin any language. 

n u m- s t mt : compoundmin digit 

Thecompoundmin statement controis the length of thetwo componentsof a compound word. This only hasan effect if 
compoundwords isturned on or if the-C flag isgiven to i speli. In that case, only words atleast as long as the given minimum 
will beaccepted as componentsof a compound. The default ÌS3 characters. 

c ha r ■ s et s : no r m- s et s [ a 1 1 • s et s ] 

Thecharacter-set section describes the characters that can be part of a word, and defines their col lati ngorder. There must 
always bea defini ti on of "normal" character sets; in addition, there may beone or more parti al definitionsof "alternate" sets 
that are used with varioustext formatters. 

norm-sets :[deftype ] charset -group 

A "normal" character set may optionally begin with adefinition of the file suffixes that makeuseof this set. Following this 
areoneor more character- set declarations. 

deftype : def stringtype name deformatter suffix* 

Thedefstringtypedeclaration gives a li st of fi le suffixes that should makeuseof the default stri ng characters defi ned as part of 
the base character set: it isonly necessary i f stri ng characters are bei ng defi ned. The name parameter is a stri ng givi ng the 
uniquenameassociated with these suffixes; often it isaformatter name. If the form atter isa member of thetroff family, 
nroff should beused for the name associ ated with themost popular macro package membersof theTeX family should use 
tex. Other names may bechosen freely, but they should bekept simple, asthey are used in ispeii's-T switch to specify a 
fo rm atter type. The deformatter parameter specifies the deformatti ngstyleto usewhen processing files with the given 
suffixes. Currently, thismust beeither tex or nroff. The suffix parameters are a whitespace-separated list ofstrings which, if 
present at the end of afilename, indicate that the associ ated set of stri ng characters should beused by default for thisfi le. For 
example, the suffix list for thetroff family typi cai ly includes suffixes such as .ms, .me, .mm, and so on. 

cha r set - gr oup : { char-stmt j string-stmt | dup-stmt}* 




A char-stmt describes single characters; a string-stmt descri bes characters that must appeartogether asastring, and which 
usually represent a single character in the target language. Either may also descri beconversion between uppercaseand 
lowercase. A dup-stmt isused to descri be alternate formsof string characters, so that a single dictionary may beused with 
several formatti ng programsthat usedifferent conventi onsfor representi ng non-ASC II characters. 

char-stmt : wordchars c h a r a c t e r ■ r a n g e 

! wordchars I o we r c a s e ■ r a n g e uppercase- r ange 

! boundarychars c ti a r a c t e r - r a n g e 

! boundarychars I o we r cas e- r ari ge uppercase- range 

string-stmt : stringchar string 

| stringchar I owercase- st r i ng uppercase-stri ng 

Characters descri bed with the boundarychars statement are considered part of a word only if they appear singly, embedded 
between characters declared with the wordchars or stringchar statements. For example, if thehyphen isa boundary character 
(useful in French), the string too - bar would bea single word, but -foo would bethesameastoo, and foo-bar would betwo 
wordsseparated by nonword characters. 

If two ranges or stri ngs aregi ven in a char-stmt or string-stmt, thefirst descri bes characters that are interpreted as lowercase 
and thesecond describes uppercase. In the case of a stringchar statement, the two stringsmust beof thesamelength. Also, 
in astringchar statement, theactual stri ngs may contai n both uppercaseand characters themselves without difficulty; for 
instance, the statement: 

stringchar "\\*(sS" "\\*(Ss" 

is legai and will not interfere with (or beinterfered with by) other declarationsof "s" and "s" as lowercase and uppercase, 
respectivéy. 

A final noteon string characters: some languages collate certain special characters as if they were stri ngs. For example, the 
German "a-umlaut" istraditionally sorted asif itwereae. ispeii isnot capableof this; each character must betreated asan 
individuai entity. So in certain cases, ispeii will sort a list of wordsinto a different order than the standard "dictionary" 
order for the target language. 

al t-sets : al ttype [ al t- st mt *] 

Because different formatters use different notationsto represent non-ASCII characters, ispell must beawareof therepresen- 
tations used by these formatters. T hese are declared as alternate sets of string characters 

alttype : altstringtype name suffix* 

Theaitstringtype statement i ntroduces each set by declaring the associ ated formatter name and fi lename suffix list. This 
name and list are interpreted exactly asin thedetstringtype statement. Following this header areoneor more alt -stmts that 
declare the alternate string characters used by this formatter. 

alr.-sr.mr. : altstringchar a 1 1 ■ s t r I ng st d- st ri ng 

Theaitstringchar statement descri bes alternate representati ons for string characters. For example the-mm macro package 
of troft represents the German "a-umlaut" asa\*:, whileTeX usesthesequenceva. If the troff versions are declared asthe 
standard versions usi ng stringchar, theTeX versions may be declared asalternates by usi ng the statement: 

altstringchar \\\"a a\\* 

When theaitstringchar statement isused to specify alternate forms, ali formsfor a particular formatter must be declared 
together asa group. Also, each formatter or macro package must providea complete set of characters, both uppercaseand 
lowercase, and the character sequences used for each formatter must becompletely disti net. Character sequencesthat 
descri be uppercase and lowercase versions of the sameprintable character must also be thesamelength. It may benecessary 
to define some new macrosforagiven formatter to satisfy these restri cti ons. (Thecurrent version of buiidhash does not 
enforce these restri ctions, butfailureto obey them may result in errorsbeing introduced into files that are processed with 

ispell.) 

An important minor poi nt isthat ispeii assumes that ali characters declared as wordchars or boundarychars will occupy 
exactly oneposition on the terminal screen. 
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A single character-set statement can deci are either a single character or a conti guous range of characters. A range is given as in 
egrep and theshell: [a-z] meanslowercasealphabetics; ra-z] meansall but lowercase, and so on. Ali character-set state- 
mentsarecombined (unioned) to produce the final list of characters that may bepart of a word. The col lati ng order of the 
characters isdefined by the order of their declaration; if a range isused, the characters are considered to havebeen declared in 
ASCII order. Characters that have case are collated nextto each other, with theuppercase character first. 

Thecharacter-declaration statements have a rather strange behavior caused by the need to match each lowercase character 
with itsuppercaseequivalent. In any given wordchars or boundarychars statement, the characters in each range are first so rted 
into ASCII collati ng sequence, then matched one-for-onewith the other range. (Thetwo ranges must have the samenumber 
of characters). Thus, forexample, thetwo statements: 

wordchars [aeiou] [AEIOU] 
wordchars [aeiou] [UOIEA] 

would produce exactly the sameeffect. To get thevowelsto match up "wrong," you would haveto use separate statements: 

wordchars a U 
wordchars e 0 
wordchars i I 
wordchars o E 
wordchars u A 

which would causeuppercaseeto beO, and lowercase 0 to bee. Thisshould normally bea problem only with languagesthat 
havebeen forced to use a strange ASC II collati ng sequence. If your uppercaseand lowercase letters both col late in thesame 
order, you shouldn't haveto worry aboutthis"feature." 

The prefixes and suff ixes sections have exactly the same syntax, except for the i ntroductory keyword: 

prefixes : prefixes flagdef* 
suffixes : suffixes flagdef* 
flagdef : flag [*jù] char : repl * 

A prefix or suffix table consists of an i ntroductory keyword and a list of flag definitions. Flagscan bedefined morethan once, 
in which case the definitions are combi ned. Each flag controlsoneor more repis(replacements), which are conditionally 
appi i ed to th e begi n n i n gs o r end i n gs of vari ous wo rds. 

Flagsarenamed by a single character char. Depending on a confi guration option, this character can be either any uppercase 
letter (the default configuration) or any 7-bit ASC 1 1 character. M ost languagesshould beableto get along with just 26 flags. 

A flag character may beprefixed with oneor more option characters. (If you wish to useoneof the option characters as a flag 
character, simply encloseit in doublé quotes.) 

Theasterisk (*) option means that this flag participatesin cross-product formation. This only matters if the fi le contai ns both 
prefix and suffix tables. If so, ali prefixes and suffixes marked with an asteriskwill beapplied in ali cross-combinationsto the 
root word. For example, consider the rootfix with prefixes pre and in, and suffixes es and ed. If ali flags control li ng these 
prefixes and suffixes are marked with an asterisk, then the single rootfix would also generate prefix, prefixes, prefixed, infix, 
infixes, infixed, fix, fixes, and fixed. C ross-product formation can produce a large number of words quickly, some of which 
may be i Negai , so watch out. If cross-products produce illegal words, munchiist will not produce those flag combi nations, and 
theflagwill not beuseful. 

repl : condì t i on* > [ - stri p-stri ng , ] append-stri ng 

The -option specifies that the associated flag isonly activewhen a compound word is bei ngformed. This isuseful in a 
languagelikeGerman, in which theform of aword sometimeschangesinsideacompound. 

A repi isaconditional rulefor modifying a root word. U p to eightconditionsmay bespecified. If the condì ti ons are 
satisfied, theruleson the rightside of the repi are appi ied, asfollows: 

1. If a strip-string isgiven, it isfirst stri pped from the beginning or ending (as appropriate) of the root word. 

2. Theappend-string isadded atthat point. 



For example, the condition . means"any word", and thecondition y means"any word ending in Y." Thefollowing (suffix) 
replacements: 

. > MENT 

Y > -Y.IES 

would change inducete inducement and flyto flies. (Iftheywere controlied by thesameflag, they would also changeflyto 
flyment, which might not bewhat waswanted. muncmist can beused to protect against thissort of problem; seethe 
command sequencegiven in the next paragraph.) 

No matter how much you might want it, the stri ngson theright must bestringsof specific characters, not ranges. The 
reasonsarerooted deeply in theway ispeii works, and it would bedifficult or impossi bleto provi de for more flexi bili ty. For 
example, you might want to write: 

[EY] > -[EY],IES 

Thiswill notwork. Instead, you must use two separate rules: 

E > -E.IES 

Y > -Y.IES 

Theapplication of repiscan berestricted to certain wordswith conditions 

condition : { . | character ] range } 

A condition isa restriction on the characters thatadjoin, and/or are replaced by, theright-hand side of the repi. Up to 
eight conditions may begiven, which should beenough context for anyone. Theright-hand side wi II beapplied only 
if the conditions in the repi are satisfi ed. The conditions also implicitly define a length; rootsshorter than thenumber of 
conditions will not pass the test. (As a special case, a condition of a single dot defines a length of zero, so thattheruleapplies 
to ali words i ndiscri mi nately.) This length isindependent of the separate test that insiststhat ali flags produce an output 
word length of at least four. 

Conditions that are single characters should beseparated by whitespace. For example, to specify words ending in ED, write 
this: 

E D> -ED, ING # As in covered > covering 

If you write this: 

ED > -ED, ING 

the effect will bethesameas 

[ED] > -ED, ING 

Asafinal, minor butimportant point, it issometimesuseful to rebuild adictionaryfileusingan incompati ble suffix fi le. For 
example, suppose you expand the r flag to generate "er" and "ers" (thus making thez flag somewhat obsolete). To build a 
new dictionary newdict that using new affixes wi II accept exactly the same list of words as the old list oiddict did usi ng old 
affixes, the-c switch of munchlist isuseful, as in thefollowing example: 

$ munchlist -c oldaffixes -1 newaffixes oiddict > newdict 

If you use this procedure, your new dictionary will always accept the same list the originai did, even if you badly screwed up 
theaffix file This is because muncmist compares the words generated by a flag with the originai word list and refusesto use 
any flags that generate ili egal words. (Don'tforget that the munchlist step takesalongtimeand eatsup temporary fi le space.) 

EXAMPLES 

Asan example of conditi onal suffixes, here is the specificati on of the s flag from the E ngl ish attix file 

flag *S: 

["AEIOUJY > -Y,IES # As in imply > implies 
[AEIOU]Y > S # As in convey > conveys 
[SXZH] > ES # As in fix > fixes 
["SXZHY] > S #As in bat > bats 
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The first I ine appi ies to wordsending in Y but not in vowel-Y. Thesecond takes care of the vowel-Y words. Thethird then 
handlesthosewordsthat end in a sibilant or near-si bi lant, and thelast picksup everyth ingelse. 

N ote that the conditions are written very carefully so that they apply to disjoint sets of words. I n parti cular, note that the 
fourth line excludes wordsending in Y aswell astheobviousSXZH . Otherwise, itwould convert "imply" into "implys." 

Although theEnglish affix filedoesnot do so, you can also haveaflag generate morethan one variati on on a root word. For 
example, you could extend theEnglish r flag asfollows: 

flag *R: 

E > R #As in skate > skater 

E > RS # As in skate > skaters 

["AEIOUJY > -Y, IER # As in multiply > multiplier 

["AEIOUJY > -Y.IERS # As in multiply > multipliers 

[AEIOU]Y > ER # As in convey > conveyer 

[AEIOUJY > ERS # As in convey > conveyers 

["EY] > ER # As in build > builder 

["EY] > ERS # As in build > builders 

Thisflagwould generate both "skater" and "skaters" from "skate." Thiscapability can bevery useful in languagesthat make 
useof noun, verb, and adjective endings. For instance, one could defi ne a single flag that generated ali theGerman "weak" 
verb endings. 

SEE ALSO 

ispell(l) 

Locai 



ip 

ìp— Lineprinter devices. 
SYNOPSIS 

#include <linux/lp.h> 

CO NFIGU RATIO N 

ip[02] arecharacter devi ces for the parallel lineprinters; they have major number 6 and minor number 02. The minor 
numberscorrespond to the printer port base addresses 0x03 bc, 0x0378, and 0x0278. U sually, they have mode 220 and are 
owned by root and group ip. You can use printer portseither with polling or with interrupts. Interruptsarerecommended 
when high traffic isexpected, such asfor laser printers. For usuai dot matrix printers, polli ngwi II usually beenough. The 
default is poi I i ng. 

D ESC RIPTI0 N 

Thefollowing iocti(2) calls are supported: 

int ioctlfint fd, LPTIME, int arg) 



int ioctl(int fd, LPCHAR, int arg) 



Sets the amount of ti me that the driver sleeps before rechecki ng the 
printer when the printer's buffer appears to befilled toarg. If you havea 
fast printer, decreasethis number; if you haveaslow printer, then 
increaseit. Thisisin hundredthsof asecond; the default 2 is 0.05 
seconda It only influences the polling driver. 
Sets the maximum number of busy-wait iterations that the polling driver 
does whilewaiting for the printer to get ready for receiving a character to 
arg. If printing istoo slow, increasethis number; if the system getstoo 
slow, decrease this number. T he default is 1000. 1 1 only i nfluences the 
polling driver. 



man, kman, port 



int ioctl(int fd, LPABORT, int arg) 

int ioctlfint fd, LPABORTOPEN, int arg) 

int ioctlfint fd, LPCAREFUL, int arg) 

int ioctlfint fd, LPWAIT, int arg) 



int ioctl(int fd, LPSETIRQ, int arg) 

int ioctlfint fd, LPGETIRQ, int *arg) 
int ioctlfint fd, LPGETSTATUS, int *arg) 

LP_PBUSY 

LP_PACK 

LP_P0UTPA 

LP_PSELECD 

LP_PERRORP 

int ioctlfint fd, LPRESET) 



FILES 



If arg ise, the printer driver will retry on errors; otherwise, it will abort. 
The default i s 0. 

If arg iso, open(2) will beaborted on errar; otherwise the error wi II be 
ignored. The default isto ignoreit. 

If arg ÌS0, then theout-of-paper, offline, and error signalsarerequired to 
befalseon ali writes; otherwise, they are ignored. T he default is to ignore 
them. 

Setsthenumber of busy-wait iterati onsto wait before strobing the printer 
to accept ajust-written characterand thenumber of iterationsto wait 
before turni ng the strobe off again to arg. Thespecification saysthistime 
should be0.5 microseconds, but experi enee hasshown the delay caused 
by the code isalready enough. Forthat reason, the default valueiso. This 
is used for both the poi I i ng and the interrupt driver. 
ThisioctiO requiressuperuser privileges. Ittakesan int containingthe 
new IRQ asargument. Asasideeffect, the printeris reset. When arg iso, 
the polli ng driver will beused, which isalso default. 
Stores the currently used IRQ in arg. 

Stores the value of the status port in arg. T he bits have the followi ng 
meaning: 

Inverted busy input, activehigh 
Unchanged acknowledge input, activelow 
U nchanged out-of-paper input, activehigh 
U nchanged selected input, active high 
U nchanged error input, active low 

Referto your printer manual forthe meaning of the signals. Notethat 
undocumented bitscan also beset, dependi ng on your printer. 
Resets the printer. N 0 argument isused. 



/dev/lp* 

AUTHORS 

The printer driver wasoriginally written byjim Weigand and LinusTorvalds. It wasfurther improved by M ichael K. 
Johnson. The interrupt code waswritten by N igei Gamble. Alan Cox modularized it. lpcareful, lpabort, lpgetstatus were 
added by Chris M etcalf. 

SEE ALSO 

mknod(l), chown(l), chmod(l), tunelp(8), lpcntl(8) 

15 January 1995 



mem, kmem, port 

mem, kmem, port— System memory, kernel memory, and system ports 
D ESC RIPTIO N 

mem isacharacter device fi le that isan imageof themain memory of the computer. It can beused, for example, to examine 
(and even patch) the system. 



Part IV: Special Files 



Byte addresses in meni are interprete as physi cai memory addresses. Referencesto non-existent locations cause errorsto be 
returned. 

Examiningand patching islikely to lead to unexpected resultswhen read-only orwrite-only bitsarepresent. 
It istypically createci by 

mknod -m 660 /dev/mem c 1 1 
chown root.mem /dev/mem 

Thefilekmem isthe same as mem, exceptthat the kernel virtual memory ratherthan physi cai memory isaccessed. 
It istypically created by 

mknod -m 640 /dev/kmem c 1 2 
chown root.mem /dev/kmem 

port issimilarto mem, but the IO portsareaccessed. 
It istypically created by 

mknod -m 660 /dev/port c 1 4 
chown root.mem /dev/port 

FILES 

/dev/mem 

/dev/kmem 

/dev/port 

SEEALSO 

mknod(l), chown(l), ioperm(2) 

Linux, 21 N ovember 1992 

mouse 

mouse— Serial mouse interface. 
CONFIG 

Serial miceareconnected to a serial RS232/V24 dialout line; seecua(4) for adescription. 
DESCRIPTION 

Thepinout of the usuai 9 pin plug asused for serial miceis 



Pin Name Usedfor 

2 RX D ata 

3 TX -12V, lmax=10mA 

4 DTR +12V,lmax = 10mA 
7 RTS +12V,lmax = 10mA 

5 GND Ground 



T his is the specifi cati on; infact, 9V sufficeswith mostmice. 

T he mouse driver can recognizea mouse by drappi ng RTS to low. About 14mslater, the mouse wi II send 0x4D on the data 
line. After afurther 63ms, M icrosoft-compatible mice will send 0x33. Other micesend different values. 



mouse 1093 

Therelativemousemovementissentasdx (positive meansright) and dy (positive means down). Variousmice can operate at 
different speeds. To select speeds, cyclethrough the speeds 9600, 4800, 2400, and 1200 bits/sec, each timewriting thetwo 
charactersfrom thetablebelow and waiting 0.1 seconds. The following table shows available speeds and the stri ngsthat 
select them: 

Bits'sec String 

9600 *q 

4800 *p 

2400 *o 

1200 *n 

Thefirst byteof a data packet can beused to synchronization purposes. 

MICROSOFT PROTOCOL 

TheM icrosoft protocol usesl start bit, 7 data bits, no parity, and 1 stop bit at thespeed of 1200 bits/sec. Data issentto 
RxD in 3-byte packets. The dx and dy movementsaresent astwo's-complement, ib (rt>) issetwhen theleft (right) button is 
pressed: 



Byte 


d6 


d5 


d4 


d3 


d2 


di 


dO 


1 


1 


Ib 


rb 


dy7 


dy6 


dx7 


dx7 


2 


0 


dx5 


dx4 


dx3 


dx2 


dxl 


dxO 


3 


0 


dy5 


dy4 


dy3 


dy2 


dyl 


dyO 



Originai M icrosoft micehaveonly two buttons. H owever, there are some three-button micethat also use the M icrosoft 
protocol. Pressing the third button is reported by sending a packet with zero movement and no buttons pressed. 

MOUSESYSTEMS PROTOCOL 

TheM ouseSystems protocol usesl start bit, 8 data bits, no parity, and 2 stop bits at thespeed of 1200 bits/sec. Data issent 
to RxD in 5-byte packets. dx issent asthesum of thetwo two's-complement values, dy issend asnegated sum of thetwo 
two's-complement values. ib (mb, rb) iscleared when theleft (middle, right) button is pressed: 



Byte d7 


d6 


d5 


d4 


d3 


d2 


di 


dO 


1 1 


? 


? 


? 


? 


Ib 


mb 


rb 


2 0 


dxa6 


dxa5 


dxa4 


dxa3 


dxa2 


dxal 


dxaO 


3 0 


dxb6 


dxb5 


dxb4 


dxb3 


dxb2 


dxbl 


dxbO 


4 0 


dya6 


dya5 


dya4 


dya3 


dya2 


dyal 


dyaO 


5 0 


dyb6 


dyb5 


dyb4 


dyb3 


dyb2 


dybl 


dybO 


SUN PROTOCOL 
















The Sun protocol uses 1 start bit, 8 data bits, no parity, and 2 stop bits at thespeed of 1200 bits/sec. Data issentto RxD in 


3-byte packets. dx 


issent as single two's-complement value, dy asnegated two's-complement value. ib (mb, rb) iscleared when 


theleft (middle, right) button is pressed: 














Byte d7 


d6 


d5 


d4 


d3 


d2 


di 


dO 


1 1 


? 


? 


? 


? 


Ib 


mb 


rb 


2 0 


dx6 


dx5 


dx4 


dx3 


dx2 


dxl 


dxO 


3 0 


dy6 


dy5 


dy4 


dy3 


dy2 


dyl 


dyO 
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MM PROTOCOL 

TheM M protocol usesl start bit, 8 data bits, odd parity, and 1 stop bit atthespeed of 1200 bits/sec. Data issentto RxD in 
3-byte packets. dx and dy aresent assinglesigned values, thesign bit indicating a negative value. ib (mb, rb) issetwhen the 
left (middle, right) button ispressed: 



Byte 


d7 


d6 


d5 


d4 


d3 


d2 


di 


dO 


1 


1 


? 


? 


dxs 


dys 


Ib 


mb 


rb 


2 


0 


dx6 


dx5 


dx4 


dx3 


dx2 


dxl 


dxO 


3 


0 


dy6 


dy5 


dy4 


dy3 


dy2 


dyl 


dyO 



FILES 

/dev/mouse a com monly used symlink pointingto a mouse device 
SEEALSO 

cua(4), bm(4) 

Linux, 10 February 1996 



nuli, zero 

nuli, zero— Data si nk. 

DESCRIPTION 

Datawritten on a nuli or zero special fi le is discarded. 

Readsfrom the nuli special fi le always return end of file, whereasreadsfrom zero always return \0 characters. 
nuli and zero are typically created by 

mknod -m 666 /dev/null c 1 3 
mknod -in 666 /dev/zero c 1 5 
chown root.mem /dev/null /dev/zero 

NOTES 

If thesedevicesarenotwritableand readable forali users, many programswill act strangely. 
FILES 

/dev/null 
/dev/zero 

SEEALSO 

mknod(l), chown(l) 

Linux, 21 N ovember 1992 



ram 

ram— Ram disk device. 



DESCRIPTIO N 

ram is a block deviceto access the ram disk in raw mode. 
It is typi cali y createci by 

mknod -m 660 /dev/ram b 1 1 
chown root.disk /dev/ram 

FILES 

/dev/ram 

SEEALSO 

mknod(l), chown(l), mount(8) 



Linux, 21 N ovember 1992 



sd 

sd— Driver forSC SI disk drives. 
SYNOPSIS 

#include <linux/hdreg.h> 

CONFIG 

The block device name has the following forni: sdip, wherei isa letter denoti ng the physical drive, and p isa number 
denoti ng the partition on that physical drive. Often, the partiti on number, p, will beleft off when the device correspondsto 
thewholedrive. 

SCSI diskshavea major device number of 8 and a minor device number of theform (16 *drive_number) +partition_number, 
wheredrive_number is the number of the physical drive in order of detection and partition_number isasfollows: 

Partition 0 Thewholedrive 

Partitionsl-4 TheDOS"primary" partitions 

Partitions 5-8 TheDOS"extended" (or "logicai") partitions 

Forexample, /dev/sda will havemajor8 and minoro and will referto ali the first SCSI drives in the system; /dev/sdb3 will 
have major 8 and minor 19 and will referto thethird DOS "primary" partition on thesecond SCSI drive in the system. 

At thistime, only block devices are provi ded. Raw devices havenot yet been implemented. 

DESCRIPTIO N 

T he followi ng ioctis are provided: 

hdio_req Returns the BIOS disk parametersin the following structure: 

struct hd geometry { 
unsigned char heads; 
unsigned char sectors; 
unsigned short cylinders; 
unsigned long start; 

}; 

A pointer to this structure is passed astheiocti(2) parameter. 
Theinformation returned in theparameter isthedisk geometry of the 
driveasunderstood by DOS! This geometry is not the physical geometry 
ofthedrive. Itisusedwhen constructing the drive's partition table, 



1096 



Part IV: Special Files 



BLKGETSIZE 



BLKRRPART 



FILES 

/dev/sd[ah]: The whole de/ice 
/dev/sd[a-h][8-8]: Individuai block partitions 

SEEALSO 

scsi(4) 



however, and isneeded for convenient operation of fdisk(l), efdisk(l), 
and iiio(l). If thegeometry information is not avai lable, zero isreturned 
forali the parameters. 

Returns the device size in sectors Theiocti(2) parameter should bea 
pointerto a long. 

Forcesare-read of the SCSI disk partition tables. N o parameter is 
needed. 

Thescsi(4) ioctisarealso supported. If the iocti(2) parameteris 
required and it ìsnull, then ±octi{2) will return -einval. 



17 Decemberl992 



st 

st— SCSI tape devi ce. 
SYNOPSIS 

#include <sys/mtio.h> 

int ioctl(int fd, int r e q u e s t [, (void * ) a r g 3 ] ) 
int ioctl(int fd, MTIOCTOP, (struct mtop * ) mt _ c md ) 
int ioctl(int fd, MTIOCGET, (struct mtget *)mt _st at us ) 
int ioctl(int fd, MTIOCPOS, (struct mtpos *)mt pos) 



DESCRIPTION 

Thest driver provi desth e interf aceto a vari ety of SCSI tapedevices. Currently, the driver takes control of ali detected 
devices of type sequential-access. T he st driver uses major device number 9. 

Each device uses two minor device numbers: a principal minor device number, n, assigned sequentially in order of detection, 
and a no-rewind device number, (n +128). Devicesopened usi ng the principal device number are sent a rewind command 
when they areclosed. Devicesopened using the no-rewind device number are not. Optionssuch asdensity or block size are 
notcoded in the minor devi ce number. Theseoptions must beset by explicit iocti() callsand remai n in effect when the 
device is closed and reopened. 

D evices are typically created by 

mknod -m 660 /dev/st0 c 9 0 
mknod -in 660 /dev/st1 c 9 1 
mknod -m 660 /dev/nst0 c 9 128 
mknod -m 660 /dev/nst1 c 9 129 

There isno corresponding block device. The character device provides buffering and read-ahead by default and supports 
readsand writesof arbitrary size (limited by the driver's internai buffer size, which defaultsto 32768 bytes but can be 
changed either by using a kernel startup option or by changing a compi le-ti me Constant). 

Device /dev/tape isusually created asa hard or soft link to the default tape device on the system. 



ioctlS 



The driver supportsthreeiocti requests. Requests not recognized by thest driver are passed to thescsi driver. The 
definitionsbelow arefrom /usr/inciude/iinux/mtio.h: 

mtioctop: PERFORM A TAPE 0 PERATIO N 

Thisrequest takesan argument of type(struct mtop *). N otall drives supportali operations. The driver returnsan E IO 
errorif the drive rejects an operation. 

/* Structure for MTIOCTOP - mag tape op command: */ 
struct mtop { 

short mt_op; /* operations defined below */ 
int mt_count; /* how many of them */ 

>; 



M agnetic tape operations: 

MTBSF 
MTBSFM 

MTBSR 

MTBSS 

MTEOM 

MTERASE 

MTFSF 

MTFSFM 

MTFSR 
MTFSS 
MTNOP 

MTOFFL 

MTRESET 

MTRETEN 

MTREW 

MTSEEK 



MTSETBLK 



MTSETDENSITY 



MTWEOF 
MTWSM 



Backward space over mt_count fi lemarks. 

Backward space over mtcount fi lemarks. Reposition the tape to theEOT 
sideof thelastfilemark. 

Backward space over mt count records(tapeblocks). 
Backward space over mt count setmarks. 
Go to the end of therecorded media (for appendi ngfiles). 
E rase tape. 

Forward space over mt_count fi lemarks 

Forward space over mtcount filemarks. Reposition the tape to theBOT 
sideof thelastfilemark. 

Forward space over mt_count records(tapeblocks). 
Forward space over mt_count setmarks. 

N o op; flushesthedriver's buffer as a side effect. Should beused before 

readi ng status with mtiocget. 

Rewind and put the drive off line. 

Reset drive 

R etenti on tape. 

Rewind. 

Seek to thetape block number specified in mt_count. This operation 
requires either a SCSI-2 drive thatsupports the locate command (device- 
specific address) or aTandberg-compatibleSCSI-1 drive (Tandberg, 
Archi ve Vi per, Wangtek,... ). The block number should beone thatwas 
previ ously returned by mtiocpos because the number is devi ce-specific. 
Set the drive's block length to the value specified in mt_count. A block 
length of zero sets the drive to variable block sizemode. 
Set the tape densi tyto the code in mtcount. Someuseful density 
codesare 

18 0x00 Implicit 0x11 QIC-525 

0X04 QIC-11 0x12 QIC-1350 

0X05 QIC-24 0x13 DDS 

0x0F QIC-120 0x14 Exabyte EXB-8200 

0x10 QIC-150 0x15 Exabyte EXB-8500 

Writemt_count filemarks. 
Writemt count setmarks. 



Set various drive and driver opti ons accordi ngto bitsencoded in 

mt count. T hese consist of the drive's buffering mode, six Boolean driver 

options, and the buffer wri te threshold. T hese parameters are ini ti al ized 

only when the device isfirst detected. The setti ngs persi stwhen the device 

isclosed and reopened. A single operati on can affectjust the buffering 

mode, just the Boolean options, or just the write threshold. 

A valuehavingzerosin thehigh-order 4 bitswill beused to set the drive's 

bufferi ng mode. T he bufferi ng modes are: 

a Thedrivewill not report good statuson writecommandsuntil 

the data blocks are actually written to the medium. 

1 T he drive may report good statuson write commandsassoon 
asall the data hasbeen transferred to the drive's internai 
buffer. 

2 The drive may report good statuson write commandsassoon 
asall the data hasbeen transferred to the drive's internai buffer 
and ali buffered data from different initiators has been 
successfully written to the medium. 

To control the write threshold, thevaluein mt_count must include the 
Constant mt_st_write_threshold logically 0 Red with a block count in the 
low 28 bits. The block count refersto 1024-byte blocks, not the physi cai 
block sizeon the tape. The threshold cannot exceed thedriver's internai 
buffer size(seethedescri ption). 

To set and clear the Boolean options, thevaluein mt_count must include 
the Constant mt_st_booleans logically 0 Red with whatevercombination 
of thefollowing options is desi red. Any options not speci fi ed are set false. 
TheBoolean optionsare 

(D efault: true) Buffer ali write operations. If thisoption isfalseand the 
driveusesafixed block size, then ali write operations must befora 
multipleof the block size. Thisoption must besetfalseto write reliable 
multi-volume archi ves. 

(D efault: true) When this options is true, write operations return 
immediately without waiting for the data to be transferred to the drive if 
thedata fits into the driver's buffer. T h e w ri te th resho I d d eterni i n es h ow 
full the buffer must bebeforeanew SCSI write command isissued. Any 
errors reported by thedrivewill beheld until the nextoperation. This 
option must besetfalseto write reliable multi-volume archives. 
(D efault: true) Thisoption causes the driver to provide read buffering 
and read-ahead. If thisoption isfalseand the driveusesafixed block size, 
then ali read operations must befora multipleof the block size. 
(D efault: false) Thisoption modifies the driver behaviorwhen afileis 
closed. Thenormal action isto write a single fi lemark. If theoption is 
true thedriverwill write two filemarksand backspace over the 
second one. 

Notethat this option should not be set true for QIC tape dri ves because 
they areunableto overwrite a fi lemark. T hese drivesdetect the end of 
recorded data by testing for blank tape rather than two consecutive 
filemarks. 

(D efault: false) Thisoption turnson various debugging messagesfrom 
the driver (effecti ve only if the driver was compi led with debug defined). 
(D efault: false) Thisoption causes the mteom operation to besent directly 
to thedrive, potentially speeding up the operation but causing the driver 



to lose track of the current file num ber normally returned by theniTiocGET 
request. If mt_st_fast_eom isfalse, the driver wi II respondto an mteom 
request by forward spaci ng over files. 
Example: 

struct mtop mt _cmd ; 

mt _ c md . mt _ o p = MTSETDRVBUFFER; 

mt _ c md . mt _ c o u n t =MT_ST_BOOLEANS | 

MT_ST_BUFFER_WRITES | 

MT_ST_ASYNC_WRITES; 
ioctl(f d , MTIOCTOP, &mt _ c md ) ; 

MTIOCGET: GET STATUS 

T his request takesan argument oftype (struct mtget *). The driver returnsan E IO errar if the drive rejectsan operation. 

/* structure for MTIOCGET - mag tape get status command */ 
struct mtget { 

long mt_type; 

long mt_resid; 

/* the following registers are device dependent */ 
long mt_dsreg; 
long mt_gstat; 
long mt_erreg; 

/* The next two fields are not always used */ 
daddr_t mt_fileno; 
daddrt mt_blkno; 

}; 

The header fi le defi nes many values for mt_type, but the current driver reports only the generi c types mt_isscsh (G eneri c 

SCSI-1 tape) and mt_isscsi2 (Generic SCSI-2 tape). 

mt_resid is always zero. (Notimplemented for SCSI tapedrives.) 

mt_dsreg reports the drive's current setti ngsfor block size (i n thelow 24 bits) and density (in the high 8 bits). These fields are 
defined by mt_st_blksize_shift, mt_st_blksize_mask, mt_st_density_shift, and mt_st_density_mask. 
mt_gstat reports generi c (device independent) status informati on. The header file definesmacros for testing these status bits: 
gmt_eof(x) The tape is positi oned just after a filemark (always false after an mtseek 

operation). 

gmt_bot ( x ) T he tape is positioned at the beginni ng of the fi rst file (always false after 

an mtseek operation). 

gmt_eot ( x ) A tape operation has reached the physical EndofTape 

gmt_sm(x) The tape iscurrently positioned at asetmark (always false after an mtseek 

operation). 

gmt_eod(x) Thetapeis positioned at the end of recorded data. 

gmt_wr_prot(x) T he drive is write-protected. For some drivesthiscan also mean thatthe 

drive does not support writing on the current medium type. 
gmt_online(x) Thelast openo found thedrivewith atapein placeand ready for 

operation. 

gmtj)_6250(x), gmt_d_i600(x), gmt_d_8B0(x) Thisgeneric status information reports the current density setti ng for 

9-track tapedrives only. 

gmt_dr_open(x) T he dri ve does not have a tape i n place. 

gmt_im_rep_en(x) I m mediate report mode (not supported). 

mt_erreg: Theonly field defined in mt_erreg i s the reco vered errar 
count in thelow 16 bits (as defi ned by mt_st_softerr_shift and 
mt_st_softerr_mask). Dueto inconsistencies in theway drives report 
recovered errors, this count isoften not maintained. 
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mt_f iieno reports the current file number (zero-based). T his value is set to 
-1 when thefile number isunknown (such as after mtbss or mtseek). 
mt_bikno reports the block number (zero-based) within the current file. 
Thisvalueissetto -1 when the block number isunknown (such as after 

MTBSF, MTBSS, Or MTSEEK). 

MTI0CP0S:GETTAPEPOSITION 

Thisrequesttakesan argument of type(struct mtpos *) and reports the d ri ve's noti on of the current tape block number, 
which isnotthesameasmt_bikno returned byiKTiocGET.ThisdrivemustbeaSCSI-2 drive that supports the read position 
command (devi ce-specific address) or aTandberg-compatibleSCSI-1 drive (T and berg, ArchiveViper, Wangtek,... ). 

/* structure for MTIOCPOS - mag tape get position command */ 
struct mtpos { 

long mt_blkno; /* current block number */ 

}; 



RETURN VALUE 

EIO 

ENOSPC 

EACCES 

ENXIO 
EBUSY 
EOVERFLOW 

EINVAL 
ENOSYS 



Therequested operation could not becompleted. 

A write operation could not becompleted because the tape reached end- 

of-medium. 

An atterri pt wasmadeto write or erase a write-protected tape. (Thiserror 

isnot detected duringopeno.) 

D uri ng openi ng, the tape device does not exi st. 

T he device i sai ready in use or the driver wasunableto allocate a buffer. 

An atterri pt was madeto read or write a variable-length block that is 

larger than the driver's internai buffer. 

An ioctio had an illegal argument, or a requested block size was i Negai. 
U nknown iocti(). 



COPYRIGHT 

Copyright 1995, Robert K. N ichols. 

Permission isgranted to makeand distribute verbatim copiesof thismanual, provi ded the copyright noticeand this 
permission noticearepreserved on ali copies. Additional permissions are contai ned in theheader of the source file. 



SEEALSO 

nrt(l) 



Linux 1.1.86, 31 January 1995 



tty 

tty— Controlling terminal. 
DESCRIPTION 

Thefile /dev/tty is a character file with major number 5 and minor number 0, usually of mode 0666 and owner.group 
root.tty. It isasynonym for the controlling terminal of aprocess, if any. 

In addition to theioctio requestssupported by the device that tty refersto, thefollowingioctio request issupported: 



vcs, vcsa 




tiocnotty Detach thecurrent processfrom its controlli ng terminal and remove it 

from itscurrent processgroup, without attachi ng itto a new process 
group (that is, set its processgroup ID to zero). Thisioctio cali only 
works on file descriptors connected to /dev/tty; thisisused by daemon 
processeswhen they areinvoked by a user at a terminal. The process 
attemptsto open /dev/tty; if theopen succeeds, it detaches itself from the 
terminal by usi ng tiocnotty, but if theopen fails, it isobviously not 
attached to a terminal and doesnot need to detach itself. 

FILES 

/dev/tty 

SEEALSO 

mknod(l), chown(l), getty(l), termios(2), console(4), ttys(4) 

Linux, 21 January 1992 

ttys 

ttys— Serial terminal lines. 
DESCRIVO N 

ttyS[0-3] are character devicesfor the serial terminal lines. 
They are typically createci by 

mknod -m 660 /dev/ttyS0 c 4 64 # base address 0x03f8 
mknod -m 660 /dev/ttyS1 c 4 65 # base address 0x02f8 
mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x03e8 
mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x02e8 
chown root.tty /dev/ttyS[0-3] 

FILES 

/dev/ttyS[0-3] 

SEEALSO 

mknod(l), chown(l), getty(l), tty(4) 

Linux, 19 December 1992 

vcs, vcsa 

vcs, vcsa— Virtual console memory. 
DESCRIPTION 

/dev/vcso is a character device with major number 7 and minor number 0, usuai ly of mode 0644 and owner root.tty. 
1 1 ref ers to t he m em o ry of th e cu rrentl y d i spi ayed vi rtual co n sol e ter m i n al . 

/dev/ vcs [1-63] arecharacter devicesfor virtual console termi nals; they have major number 7 and minor number 1 to 63, 
usually mode 0644 and owner root.tty. /dev/vcsa[o-63] arethesamebut include attri butes and areprefixed with four bytes, 
givi ng the screen dimensionsand cursor position: lines, coiumns, x, y.(x =y =0 at the top-left corner of thescreen.) 
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These replace the screendump ioctisof consoie(4), so the system administrator can control access usi ng fi lesystem permis- 
sions. 

T he devicesfor the fi rsteight virtual consoles may Pecreated Py 

f or x in 0 1 2 3 4 5 6 7 8; do 
mknod -ni 644 /dev/vcs$x c 7 $x; 
mknod -ni 644 /dev/vcsa$x c 7 $[$x+128]; 
done 

chown root.tty /dev/vcs* 

N o iocti() requests are supported. 

EXAMPLES 

You can do a screendump on vt3 Pyswitchingto vtl and typingcat /dev/vcs3 >foo. 

This program displays the character and screen attri butes under thecursor of thesecond virtual console and then changesthe 
Packground color there: 

#include <unistd.h> 
#include <stdio.h> 
#include <fcntl.h> 

void main() 
{ int fd; 

struct {char lines, cols, x, y;} scrn; 
char eh, attrib; 

fd = open( "/dev/vcsa2" , 0_RDWR); 
(void)read(fd, &scrn, 4); 

(void)lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0); 

(void)read(fd, &ch, 1); 

(void)read(fd, &attrib, 1); 

printf ( "ch= '%c ' attrib=0x%02x\n" , eh, attrib); 

attrib "= 0x10; 

(void)lseek(fd, -1, 1); 

(void)write(fd, &attrib, 1); 

} 

FILES 

/dev/vcs[0-63] 
/dev/vcsa[0-63] 

AUTHOR 

Andries Brouwer (aeb@owi.ni) 

HI STORY 

Introduced with version 1.1.92 of the Linux kernel. 
SEEALSO 

console(4), tty(4), ttys(4), selection(l) 

Linux, 19 February 1995 
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intro 

intro— Introduction to fi le formate. 
D ESC RIPTIO N 

T his chapter descri bes vari ous fi le formate and protocols, and theused C structures, if any. 
AUTHORS 

Look at the headerof the manual page for the authors and copyright conditions. Notethatthesecan bedifferentfrom page 
to page! 

Linux, 24 J uly 1993 

active, active. times 

active, active. times— List of arti ve Usenet newsgroups. 
D ESC RIPTIO N 

The fi le /news/iib/active lists the newsgroups that the locai site receives. Each newsgroup should belisted only once. Each 
linespecifies one group; their order in thefiledoesnot matter. W ithin each newsgroup, articles are assi gned uniquenames, 
which are monotonically increasing numbers 

If an arti eie is posted to newsgroups not menti oned in thisfile, those newsgroups are ignored. If no valid newsgroups are 
specified, the arti eie i s fi led into the newsgroup "junk" and only propagated to sites that receive the "junk" newsgroup. 

Each line consists of four fields specified by a space 

n a me hi ma r k o ma r k f I a g s 

T he first field is the nameof the newsgroup. Newsgroups that start with thethreecharactersto. aretreated specially; see 
innd(8). Thesecond field is the highest article number that has been used in that newsgroup. The third field is the lowest 
articlenumber in the group; this number is not guaranteed to be accurate and should only betaken asa hint. N otethat 
becauseof article cancellations, theremay begaps in thenumbering sequence If the lowest articlenumber isgreater than the 
highest articlenumber, thereareno articles in the newsgroup. To makeit possi bleto update an entry in-placewithout 
rewriting the enti re fi le, thesecond and third fields are padded with leading zerosto makethem afixed width. 

Thefourth field can contain one of the following flags 



y Locai postings are allowed 

n No locai posti ngs are allowed, only remote ones 

m Thegroup ismoderated and ali postingsmust beapproved 

j Articles in thisgroup are not kept but only passed on 

x Articles cannot be posted to this newsgroup 

=f o o . bar Articles are locally fi led i nto thef oc bar group 



If a newsgroup has the j flag, then no articles wi II befiled into that newsgroup and locai posti ngs to that group should not be 
generated. If an article for such a newsgroup is received from a remote site, it will befiled into the "junk" newsgroup if it is 
not cross-posted. This is different from not having a newsgroup listed in the fi le because sites can subscribeto j newsgroups 
and the article will be propagated to them. 

If thefourth field of a newsgroup starts with an equal sign, then the newsgroup isan alias. Articles can be posted to thegroup 
but will betreated as if they were posted to thegroup named after the equal sign. Thesecond and third fields are ignored. 
N otethat the newsgroup header is not modified (Alias groups are typi cai ly used duri ng a transiti on and are typically created 
with ctiinnd(8)). An alias newsgroup should not point to another alias. 
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The file /news/iib/active.nmes provides a chronological record of when newsgroups are created. This file isnormally 
updated by innd(8) whenevera ctnnnd newgroup command isdone. Each lineconsist of threefields: 

n a me t i me creator 

The first field isthenameof the newsgroup. The second field is the ti me it was created, expressed asthenumber of seconds 
sincetheepoch— atime_t; seegettimeofday(2).Thethirdfield istheelectronic mail addressof theperson who created the 
group. 

HI STORY 

W ritten by Rich $alz (r-saizuuunet.uu.net) for InterN etN ews. 
SEEALSO 

ctlinnd(8), innd(8) 



adduser.conf 

adduser.conf— Confi guration fileforadduser(8) and addgroup(8). 

SYNOPSIS 

/etc/adduser.conf 

DESCRIVO N 



Thefileadduser.cont contai ns defaults for the programsadduser(8) and addgroup(8). Each option takes the form opti on 

vai ne . 



Thevalid configuration optionsare 

Thelogin shell to beusedforall newusers. Defaults to /bin/bash. 
Thedirectory in which new homedirectoriesshould be created. Defaults to /home. 
The directory from which skeletal user configuration fi les should becopied. D efaultsto / 
etc/skel. 

Specifiesthe lowest valid U ID for normal userson your system. IDsbelow firstjjid are 
reserved for administrativeand system accounts. D efaultsto 1000. 
T he usergroups variablecan beeitheryes orno. If yes, each created userwill begiven their 
own group to use as a default, and their setup will arrangeto havethem create fi les group- 
writableby default, thusallowing them to effectively usegroup-writeablefilespaceareas 
(such as/usr/iocai). If no, each created userwill beplaced in the group whoseGID is 
users_gid, and they will create fi les not group-writeableby default. 
If usergroups isno, then users_gid istheGID given to ali newly created users. The default 
value is 100. 



DSHELL 

DHOME 

SKEL 

FIRSTJJID 
USERGROUPS 



USERS GID 



FI LES 

/etc/adduser.conf 

SEEALSO 

adduser(8) 



Debian GNU/Linuxversion 1.94 
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aliases 

aliases— Al iases fi le for sendmail. 

SYNOPSIS 

aliases 

D ESC RIPTIO N 

T his fi le describes user I D aliases used by . The fi le resi desi n and isformatted asaseriesof linesof theform: 

name : ri a me_ 1 , n a me_ 2 , na me_ 3 , ... 

Thename isthenameto alias, and thename_n are the aliases for that name. Lines beginningwith whitespacearecontinuation 
li nes. Lines beginningwith # are corri ments. 

Aliasing occursonly on locai names. Loopscannot occur becauseno messagewill besent to any person morethan once. 

After aliasing hasbeen done, locai and valid recipientswho havea .forward filein their homedirectory havemessages 
forwarded to the list of usersdefined in that file. 

This isonly the raw data fi le; theactual aliasing information isplaced into a binary format i n the fi les and usi ng the program 
newaiiases(l). A newaiiases command should beexecuted each time the aliases file ischanged for thechangeto takeeffect. 

SEEALSO 

newaiiases(l), dbm(3), sendmaii(8), "Sendmail Installation and Operation Guide" "Sendmail: An Internetwork M ail 
Router." 

BUGS 

Becauseof restrictions in dbm(3), a si ngle alias cannot contai n morethan about 1000 bytes of information. You can get longer 
aliases by "chaining" — that is, makingthelast name in the alias a dummy name that isacontinuation alias. 

HISTORY 

The aliases fi le format appeared in BSD 4.0. 

BSD 4, 10 May 1991 

cfingerd 

cfingerd— Configurale finger daemon. 
SYNOPSIS 

cfingerd [-c| -d | -e |-o |-v] 



-c Check configuration 

-d Run as daemon, not inetd 

-e Emulate locai fi ngerwithout inetd 

-o Turn off ali fi nger queries 

-v Request version information 



-c checksyour installed configuration. This makessurethere are no existing errors in thecurrent cfingerd. conf file, 
-d runs cfingerd asadaemon. Don't run cfingerd thisway if you'reusing inetd. 

-e allowsyou to emulate a locai finger on a user that existson your system. Thismakesit so that you can test cfingerd on 
your system before instai ling it. U si ng the -e di recti ve is the sameas instai li ng the software, typing finger user name @ and 
getti ng the output. Usi ng -e use ma me doesthesame. 



cfingerd 




-o turnsoff ali finger queries. Thismakesit so that no onecan finger your system— no matter what they try to do. 
-v requests cfingerd version information. 

D ESC RIPTIO N 

cfingerd is a total ly new and total ly confi gurable finger daemon— oneof the first. It utilizes the finger port (port 79) to 
provide useful information on each user on your system. H owever, cfingerd providesauniquetwist. 

cfingerd wasdesigned for the sole purposeof making output on finger queries confi gurable. If you wantto changeany text 
that isdisplayed duri ng finger queries, you can configure the finger daemon to display just about anythingyou want. 

cfingerd also takes into account any security breachesand atterri ptsto closethem. With .nofinger files, this isdisplayed 
instead of finger information, making it possi ble for usersto keep themselves relati vely anonymousfrom outsideusers. 

WHY WASITDONE? 

Theanswer issimple: security. M any sitesturn off finger for the reason that they don't want outsideusers to seewho'son 
their system or get information about a specific user on their system. Thisseemed unfair to therest of theusersoutthere, so 
this program wascreated. Thosesiteswerewaiting for this typeof program. M any sites that originai ly had the r finger turned 
off turned them back on because of cfingerd. 

M any sites compiai ned that they wanted the capabi lity to create a fake user or a user that doesn't exist but cai Is a prewritten 
shell script, cfingerd takes this into account and provi des the best method possiblefor creating such scripts. (See 
cfingerd.conf(5) for more information on the confi guration file) 

FEATURES Cfingerd PRO VIDES AND DESCRIPTIONSOF EACH 

cfingerd wastotally rewritten. Why is this?T he older version of cfingerd had quiteafew bugs, and it didn't qui te do ali the 
thingsthat cfingerd now does. This new version wastotally revamped, and most of the bugs that were in the older version of 
cfingerd wereremoved in thisone. The code i salso more compact. 

H eader and footer displayswerea big part of the originai releaseof cfingerd and shall conti nueto remai n in ali versions. 
H eadersand footers areonly displaysatthebeginningand ending of ali finger displays and areused asunique little 
adverti sements. 

Thelast timedisplayed isalways a criticai issue. It'scovered in cfingerd. cfingerd simply showshow many ti mes this user is 
connected, what their idletimeison each tty they'reconnected to, and whether they areaccepting messages. If they'renot 
accepting messages, a [mesg-n] display wi II beshown. This di splay also shows thelast ti me mail was read and whether this 
user hasmail. 

Stand-alone and inetd support iscompiled into the program, butonly inetd support isgiven for the ti me bei ng. The reason 
isthat I havenot yet added theoption for stand-alone daemon mode 

.nofinger filesareused when a user wantsto remai n anonymous. Thesefilesshould beplaced in their homedirectoriesand 
can display anything they want. There'sjust a few restri cti o n s. These .nofinger display files cannot becharacterdevices, 
directories, FIFOs, soft or hard links, or anything else of that cali ber. They must only benormal files. 

Fake users were supported for thesimplefactthat many sites wantto create userswho don't exist and makethem executea 
shell. If you wantthisdone instali afakeuser. Read cfingerd. conf(5) for more information on these useful options 

Service displays were used to show what fake users you have instai led on your system. These can beformatted however you 
want and areexplained in cfingerd. conf(5). 

Searchingforusernamesisapowerful feature that cfingerd takes full advantageof. If you are looking for a specific username 
on the system or don't know what their nameis, simply use the searcn. username di recti ve with cfingerd, and you can search 
for a user on your system. 

Searching for usernames is not case sensitive. If you are searching for a specific username or part of the user's name, chances 
are that it'll bedisplayed. 
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There'salso an option to display your public PGP key if you haveone. Thisis very useful if you want to keep your mail or 
other informati on secret to yourself and don't want "big brother" watchi ng over your shoulderas you talk amongyourselves. 
(Thanksto Andy Smith forthis patch.) The standard pian file is .pian, project is .project, and PGP info is .pgpkey. 

Remember, any or ali of theseoptionsstated can beturned on or off at will. If you want aspecific option turned off, turn it 
off. 

ERROR MESSAGES 

Any errar messagesthat result arefairly easy to debug if you know whatto lookfor. 

Segmentation violati ons don't alwaysoccur, but if they everdo, you can pretty easily figure outwhat'sgoing on. Unfortu- 
nately, ctingerd doesn't have any compati bility with older cfingerd.cont files, so if you get a segmentation violation, this 
means(usually) that your cfingerd.cont fileneedsto bereplaced. 

Time-outs usuai ly mean that a script hastimed out or a connection to another sitetimed out. 
SYSLOGGING MESSAGES 

There'sno real wayto descri be syslog messages because they can bechanged asthesystem administratorchooses. Although, 
examplescan begiven based on the standard configuration that was distri buted. 

If any IP addressescannot bematched to a hostname, SYSLOG will display ip: Hostname not matcned. 

If the renice fails(to maketheprogram run atthehighest priority), then syslog will display Fatai - Nice died: (r eas on ). 

Ifthereisno buffer information iswaiting in thesTDiN buffer, syslog will display stdin contains no data. 

If atrusted host fi ngers your site, a<- Trusted will appear. 

If a rejected host fi ngers your site, a<- Rejected will appear. 

If root isfingered on your site, it will display Root. 

If a service listing wasfingered on your site, syslog will display Service ìisting. 
If a user listing was requested, syslog will display user ìisting. 
If afakeuserwasrequested, syslog will display Fake user. 

If whois data was requested, syslog will display wnois request. (N ote that whois was not implemented in this release because 
itwasn't RFC compliant.) 

Any extra information pertaining to the incoming finger isdisplayed in the sysloggi ng area. (It'salso recommended that you 
reconfigure sysiog. cont (5) to display to an unused VT.) 

BUGS 

When data isforwarded to other sitesfor f ingerì ng, it shows the output of the system that itforwarded the finger request to. 
Thishasgot to change. 

On ELF-specific systems, services listsusually show a bit of garbageat thebeginning of the finger display. This doesn't 
appear to beaproblem on a. out systems, so if you haveELF, you mightwantto compilectingerd asa.out if thisbecomesa 
problem. 

PLANS 

Any other optionsor improvementswill probably comefrom user suggestions. 

Later planswill mean you can define your own display formatsfor the finger display. This means that you can redefinehow 
you want your finger display to look. 

CONTACTING 

If you li ke the software and you want to learn moreabout itor want to seeafeatureadded to itthat isn't already here, write 

tO khollis@bitgate.com. 
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l'vereceived callsatwork pertai ning to the software, and although I appreciate thefact that peoplelike the software I wrote, 
l'd appreciateit if you leavemee-mail and be considerate. 

cfingerd isnow bé ng maintained by M ichael Jarvis. Any additions after cfingerd 1.2.3 should bedirected toward M ichael. 

YOU can reach him atmjarvisgqns.com. 

If you wantto seeother projects that Bitgate Software iscurrently developing, check outtheWeb page at http:// 
www.bitgate.com/. Thiswill contai n ali theupdate information on the software that is being developed and that isalready 
released. 

SEEALSO 

cfingerd.conf(5), finger(l), userlist(l), syslog.conf (5) 

cfingerd 1.2.3, 24 May 1996 



cfingerd. conf 

cfingerd . conf — C onfi gurabl e fi nger daemon conf iguration fi le. 

SYNOPSIS 

/etc/ cfi ngerd.conf 

D ESC RIPTIO N 

cfingerd. conf is the configuration filefor cfingerd. Thishasbeen total ly rewritten to support a more readable confi guration 
file. Thisversion of thenew configuration fileisnot compati blewith theolder versi onsfrom 1.0.3 or earlier. 

Each line in the configuration file is split into threesections files, config, and hosts. Each oneof thosesectionsis split into 
subsections. 

Subtext of each option iseither Boolean options, stri ng options, orswitchableoptions, ali changeableby the system 
administrator. 

Each section is split into a seriesof sectionsthat resemblesC-typedefinition; it'snot exact but closeenough to befamiliar. 
There'sonly oneexception: Thesearenot case sensi ti ve. Any casing will do as long as the option i slegai. 

Thus, each option isformatted likethis: 

OPTION sub_option_name = { 

(tab/space) stringoption = "string format", 

(tab/space) boolean_option = [BOOL, BOOL], 

(tab/space) +/-internal_config_option 

(tab/space) host.name.here 

} 

Thisshowsthat string options are stri ngsput into quotes, Boolean options are given asmuE and false, switchable options 
aregiven with the + or - di recti ve and hostnamesareused as substri ngs so that wildcards are not necessary. 

You can add commentsusingthehash mark (#) at thebeginningof the li ne. Please note that no commentsareallowed inside 
of an option. 

DISPLAY FILES SECTION (FILES display files) 

Each option here is a stri ng option. These are formatted astheexampleshows. 

plan is the pian fi le that isused when displaying a pian. The standard here is .pian. 

project isthe project fi le that isused when displaying a project descri ption. T he standard here is. project. 

pgp_key is the Pretty-Good- Privacy fi le that isshown when displaying a public or private key. The standard hereis .pgpkey. 
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(The preceding threefiles must beworld readablebut should not beworld writable. This makessurethat cfingerd can read 
the fi le once it becomesthe"nobody" U ID/GID . Thisisgenerally a good ideafor protection.) 

no_finger isthefilethat isshown when a user wantsto remai n anonymous. This isusually the case with root users(which 
should be standard anyway). The standard hereis .nofinger. This file can only bea standard displayablefile. 

logfile isthefilethat isused to keep logsof everythingthat happensto both your system and the finger program. These logs 
arekept as backupsfor your finger fi le and can beused to guard against attacks agai nst your system if a finger attack occurs. 
Remember, the cfingerd. conf fi le is root owned, so this fi le should bekept in asafe, hidden place. 

header_display isthefilethat isdisplayed atthetop of each finger display. T he standard hereis /etc/cfìngerd/ 

top_finger.txt. 

footer_display isthefilethat isdisplayed at the end of each finger display. The standard hereis /etc/cfingerd/ 

bottom_finger.txt. 

no_user_banner isthefilethat isdisplayed if the user doesn't exist. The standard hereis /etc/cfingerd/nouserj>anner.txt. 
no_name_banner isthefilethat isdisplayed if no namewasspecified in a finger display. This isused in conjunction with the 

SYSTEM_LIST Option (explai ned later). The Standard hereis/etc/cfingerd/nonamejianner.txt. 

rejected_banner isthefilethat isdisplayed if a rejected host tries to finger your system for any reason. The standard hereis / 

etc/cfingerd /rej ected_banner.txt. 

FINGER DISPLAY CONFIGURE SECTION (CONFIG finger display) 

Each option in this section isBoolean. The way this works isasfollows: The first Boolean option is the setti ng for a remote 
host or a host that fingers you from theoutside. Thesecond Boolean option isthe setting for the locai host ortrusted host. 
This is what peoplefrom your own system will see. 

Each option hasa - or + option. This is for user- overridable opti ons, which will bein thenext releaseof cfingerd. These will 
allow usersto mani pulateif this information isdisplayed when that specific user isfingered. 

header_file displays the header fi le at the begi nni ng of each fi nger query. 

footer_file displays the footer file at the end of each finger query. 

login_id displays the login ID of that particular user. 

realjame displaysthe real nameof that particular user. 

directory displaysthe user's directory. 

shell displays the user's shell. 

roomjwmber displays the user's room number. 

workjwmber displays the user's work phone number. 

home_number displays the user's home phone number. 

other displays the user's other information. 

last_time_on displays the last timetheuser logged into thefingered system. 
if_online displayswhethertheuser iscurrently logged into thefingered system. 
time_mail_read di splays the last ti me that the f i ngered user read mail. 
day_mai l_read displays the last day that thefingered user read hisor her mail. 
originatici displays the site from which theuser logged in (if applicatile). 
plan di splays the user's pian file. 
project displays the user's project fi le. 
pgp displays the user's Pretty-G ood- Privacy key file. 
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no_name_banner displays the banner if no usernamewas given. 

rej ected_banner d i spi ays th e re] ected banner if the site fingering your system was in the banned-site listing. 
system_list displays the system list if onewasrequested. 
no_name displays the no-name display file if no user was sei ected. 

INTERNAL CONFIG CONFIGURE SECTION (CONFIG internai config) 

Each item in thissection isaswitchableoption. Thismeansthat a + beforetheitem isturned on and a - beforetheitem is 
turned off. 

allow_multiple_finger_display allowsyou to givea sorted output of ali userson morethan onespecific system. Thisisuseful 
when you havemorethan onelSP machine, locateci in different citiesor even states. 

allow_searchable_finger allowsyou to let others outsideyour system (orwithin it) to search fora speci fic usernameby using 

the search.us er na me directive. 

allow_no_ip_match_finger allowsyou to let sites finger your system if a hostnamecould not bematched to their IP address 
successfully. 

allow_user_override will allow your usersto overri de specific optionsin the finger display section that you enable. 

allow_userlist_only will allow other sites that are fingering your system for a specific compi led user list to finger your system 
and get a user listing of who's online Thiscould bea security risk, so you mightwant to turn thisoption off if you feel it'sa 
security risk. 

allow_finger_forwarding will allow other si testo forward finger requeststo a different machine if the user could not be 
located on thecurrent machine. (In order to use thisoption, you must havetheHosTs finger forward option set and have 
other sites in there.) 

allow_strict_formatting makes the finger display remove ali returnsbetween display options. Thismakes the finger di splay 
look horri ble (as with GNU Finger or the other generic fingers) and makes your system look, well, "generic." 

allow_verbose_timestamping makes the ti mestamp that isdisplayed (at any place) very verbose. For instance, whereit used to 
say 

On since Sat Aug 12 03:43PM(PDT) 

would now beshown as 

On since Sat Aug 12, 1995 03:43PM(PDT) 

{Basi cally, allow_verbose_timestamping just takes up moreroom on thedisplayfield.) 

allow_nonident_access letsyou only allow connectionsfrom sites that run theident daemon (or RFC 1413-compliant 
program.) Thisisfor security sake and isagood measureagainst unknown userstryingto finger your system. If thisoption is 
enabled, userswho do not haveidentd running on their system (such as W i ndows users) will beableto finger your system. 
Systems not running identd will return unknown as the user ID and will not bepermitted to finger a user on your system. 

allow_finger_logging enablescfingerd to use the logfile fileto storeany logsof activity that happen to your system via 
finger. 

allow_line_parsing makes ctingerd parse each lineof every display fi le (includi ng the pian, project, and pgp files) for any 
cfingerd-specifics commands. If any arefound, ctingerd will parse thesecommands and display correct information 
accordingly. Otherwise, if this isturned off, the display will appearwithout parsed commands. 

allow_execution will allow users to execute seri pts in place of their .pian, .project, and .pgp files. This is used to display the 
standard output of another program di rectly to thescreen of the user. Keep in mind that this is a huge security risk if you 
chooseto useit. It'snormally suggested that thisoption remai n off, but you can turn it on if necessary. N evertheless, these 
programs are called as nobody . nogroup. 
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allow_fakeuser_finger turnson or off the fake user option in cfingerd. If you want fake users to bedefined and availableto 
befingered, you will want to enable this option. Thiscan bea security ri sk in some instancesif you allow for searchable 
fingersand your script callsan execute routine on thatvariable. Chancesarethat'll never happen. 

allow_userlog will allow usersto keep track of who hasfingered them and atwhattime A little fi le cai led .fingeriog will 
appear in their directory, which they can examineto seewho hasfingered them. If you don't care about this, you can disable 
it. Otherwise, it'snotabad idea. (Italso logsroot fingere aswell.) 

SYSTEM LIST SITES C 0 N FIG U RE SECTIO N (CONFIG system list sites) 

This isjust a series of hostnamesthatyou wantto fingerwhen displaying your user-list display. If you havemorethan one 
system that you want to show, simply puttheir hostnamein this list, separated on a lineby itself. 

Forexample, if I have a separate ISP system that l'm runningon the side, say chatiink.com, I would changemy configuration 
to say 

CONFIG system_list_sites = { chatlink.com, localhost } 

Remember, if you are I isti ngonly acoupleof sites, list the sites you will wantto havelisted (in order) first. The ending entry 
must bei oc ai h os t or the finger listi ng will not include your site If you include i oc ai host anywhereelsein the list, it will 
stop onceit hasreached the i oc ai host entry, so remember to list it last! 

I wantto get a user listingfrom my own machine and from chatnnk.com's system. This would be automati cai lyformatted 
nicely (sorted and parsed) and would display on thescreen in sorted order. This program isusually used in tandem with the 
supplied useriist(l) program. 

If no system list sites are specified, multiple system sites will not bespecified. 

TRUSTED HOSTSECTION (HOSTS trusted) 

T his is a listi ngof the sites that you allow to finger your system exclusively, givingthem the same access that your locai users 
would get. In otherwords, they are treated asi oca! host users. 

Each site that you list in thissection should be separated by usi ng the , di recti ve. You can include up to 80 sites in this 
listing. 

Wildcardsaresupported in thissection, and you can use them in the regex format aswell. Any wildcardswith *, ?, or any 
other regex wildcard matchingcharacterwill work. IP addresseswill also work. H ostnamesarecompared case in sensi ti ve. 

REJECTED HOSTSECTION (HOSTS rejected) 

This is a listing of the sites that you do not allow to finger your system. These sites don't getto finger anyone(or anything 
for that matter) on your system, regardlessof whatthey try to do. In essence, finger iscut off to that particular system. 

Each site that you list in thissection should be separated by usi ng the , di recti ve. You can include up to 80 sites in this 
listing. 

Wildcardsaresupported in thissection, and you can use them in the regex format aswell. Any wildcardswith *, ?, or any 
other regex wildcard matchingcharacterwill work. IP addresseswill also work. H ostnamesarecompared case in sensi ti ve. 

FORWARD ED HOSTSECTION (HOSTS finger forward) 

T his is a listi ngof sites that are used to forward a finger query to when a finger request was processed butthat particular user 
wasnotfound on theassociated system. It will step through this listing, and it will search for the user in question. If the user 
could not befound, then it will step through to thenext host and thenext, until it findsone 

Each site that you list in thissection should be separated by usi ng the , di recti ve. You can include up to 80 sites in this 
listing. 

Wildcardsaresupported in thissection, and you can use them in the regex format aswell. Any wildcardswith *, ?, or any 
other regex wildcard matchingcharacterwill work. H ostnamesarecompared case insensitive. 

If you do not specify any forwarding sites in thissection, fingerforwarding will bedisabled for your system. 
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FINGER STRINGSCONFIGURE SECTION (CONFIG finger strings) 

Each option in this section is a string that can bechanged to fityour needswhen di spi aying finger information. These strings 
are li mited to about 20 characterson the display. (If you use more than 20, the finger display wi II end up looking strange) 

user_name is the stri ng that isdisplayed when theuser'susernameisshown. 

real_name isthe string that is displayed when the user's real nameisshown. 

directory is the stri ng that isdisplayed when the user's directory isshown. 

shell isthe string that isdisplayed when the user's shell isshown. 

room_number is the stri ng that isdisplayed when the user's room number isshown. 

work_number is the stri ng that isdisplayed when the user's work phone number isshown. 

home_number isthe string that isdisplayed when the user's home phone number isshown. 

other isthe string that isdisplayed when the user's other display information isshow. 

plan isthe string that isdisplayed when the user's pian isshown. 

project isthe string that isdisplayed when the user's project isshown. 

pgpkey isthe string that isdisplayed when theuser's PGP key isshown. 

no_plan isthe string that isdisplayed when the user doesn't havea pian fleto show you. 

no_project isthe string that isdisplayed when the user doesn't havea project fleto show you. 

no_pgp isthe string that isdisplayed when the user doesn't havea PGP key fi le to show you. 

wait isthe string that isshown when the system gathers information from other sitesfor a user listing. 

INTERNAL STRIN G S CO N FIG U RE SECTION (CONFIG internai strings) 

T hese strings are changeable and can beany length you want(within reason). These strings are concatenated intothe 
syslogging display when the appropriate finger hasbeen issued. This section also includes errar messagesthat may occur. 

no_ip_host isshown when thereisno hostnamethat matches the incomi ng IP address. Thisusually indicates that either the 
site didn't register itsIP address with the I nterN IC or it is comi ng from a hacked site. 

renice_fatal isshown when thesystem failed to changetheexecution priority on thecurrent processof cfingerd. 

stdin_empty isshown when theinput buffer on thecfingerd port isempty. (This should never really happen; it'sherefor 
sanity.) 

trusted_host isshown when atrusted host fingers your system. If you do not specify a trusted host, cfingerd will insert 
o c a i host into thisfield. 

rejected_host isshown when arejected host fingers your system. If you do not specify a rejected host, cfingerd will insert 
0.B.0.0 into thisfield. 

root_finger isshown when auserfingersroot. 

service_finger isshown when a user requestsfakeuser servicesfrom your system. 
user_list isshown when a user requestsauser listing from your system. 
fake_user isshown when a user fi ngers a fake user from your system. 

whoisjjser isshown when a user fi ngers a user with aWH 0 IS query. (This option is not yet available.) 

finger_deny isshown when a user triesto finger with aforward request such asuser ?host i@host 2 . T his is not supported 
becauseit could result in finger loopsand a lot of traffic. 

SiGNAL STRINGSCONFIGURE SECTION (CONFIG signal strings) 

This section isused in changing the output that isgiven when a system crashes, or a signal iscaught, and reported to the 
finger output. 
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T h e su ppo rted caugh t si gn al s are as f o 1 1 ows 

SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGFPE, SIGUSR1 , SIGSEGV, SIGUSR2, SIGPIPE, SIGALRM, SIGTERM, SIGCONT, 
SIGTSTP, SIGTTIN, SIGTTOU, SIGIO, SIGXCPU, SIGXFSZ, SIGVTALRM, SIGPROF, SIGWINCH 

FINGER PRO G RAM S FILES SECTIO N (FILES finger programs) 

Thesearetheprogramsthatarecalled when a specific action istakeon the finger display. 

finger isthefilethat isused when a user listing isrequested from your machine. Thisisused in the standard user list and in 
thesorted user list, so it iswiseto use the standard here: /usr/sbin/useriist. 

whois is the program that isused when a W H 0 1 S request isdoneon a specific user. 

FIN GERFAKEUSERS FILES SECTIO N (FILES finger fakeusers) 

T hese are the ever-popularfakeusers that you can create on your system. Theseusers are ones that don't exist (and should 
not exist, forthat matter). T hese are, instead, treated as normal seri pts that can becalled foryour use 

The format isasfollowsfor fakeusers: 

fake_username Seri p t _ n a me SEARCHBOOL seri p t 

f a k e _ u s e r n a me is the name of thefake user you want to request. M akesurethat thisis a user that does not exist on your 
system. Keep in mind that if you create a fakeusername and that user al ready exists, thefakeusernamewill beshown. 

seri p t _ n a me is the standard name of your script. Thisisused in the display of your servi ces listing. 

searchbool specifi es whether parameterscan besent to that specific fake user. If you decidete use the searchbool option 
(true in thiscase), the passed vari ables are 

$1 First passed option 

$2 Second passed option 

$3 T hi rd passed option 

$4 Fourth passed option 

(If morethan four optionswere passed to this, the request wi II beignored, and an errar messagewill bereturned to the user 
who requested thefinger request.) 

script is the location of your script. It should bechmod 700 and readableonly by root. 

If you do not specify any fake users, a fake user called None will becreated. Thisis a fake user that doesnothing and calls / 
dev/nuii for thescript. 

SERVICES H EADER CON FIG U RE SECTIO N (CONFIG services header) 

Thisis the display that isgiven during a services finger. It should beformatted the sameway that you want itto display on 
thescreen. 

When specifyingthefingerformatted options, you should specify them asC formatted stringsaswell, with thestandard 
options. This should alwaysbegiven last in the display. 

An exampleof thisis 

Welcome to this system 's services! 
User: Service name: Searchable: 

%-8s %-20s %-s 

Remember to keep theformat string last or a sigsegv will result. 

SERVICES PO SITIO N S CO N FIG U RE SECTIO N (CONFIG services positions) 

This speci fi es where in the precedi ng display string that the informati on from a servi ce listing isto appear. T hese numbers 
can beanywherebetween 1 and 3. 
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user specifies the position of theusernamelisting. 

service specifies the position of theservicefull-namelisting. 

search specifies the position of theBoolean search display. 

CONTACTING 

If you likethis program and havequestionsor commentsabouttheprogram'sfunctionality orwhat-have-you, writeto 

khollis@bitgate . coni. 

Asalways, I appreciateany suggestionsor bug reportsyou might have, so bringthem on! 
SEEALSO 

cfingerd(8), cfingerd. text(5), userlist(l), finger(l), regex(3), regexp(3) 

16 May 1996 



cfingerd text r u I es 

EXPLANATION 



cfingerd offers different commandsthat can beplaced in text fi lesto display corresponding information. Each command 
used with cfingerd in text files begi ns with adollar sign ($). This usuai ly indicatesto cfingerd that when it'sdisplaying a file, 
it parses the command directly after that character. 

If you want to display a raw $ sign, simply put two $ signstogether, or $$. 
TEXTCOMMANDS 

Thefollowing isalistof text commands and what they do. Each of the text commandscan bein any text case; it doesn't 
m after. 

$center D isplays the enti re contents of the line. This command must start at the beginning of the 

line. This isavery common command. 
sdate D isplays the current system date in the format of M M/D D/YY. 

stime D isplays the current system ti me in the format H H :M M A/PM (ti me zone). 

sident D isplaystheidentity of the current person fingeringyour system. 

$compile_datetime D i splays the date and timeof which thecurrent issueof cfingerd wascompiled on your 

system. 

sversion D isplaysthe current version of cfingerd. 

$exec Executes a file with x parameters after it. The$EXEC command must beon a line byitself 

in orderto function properly. The command isexecuted asnobody.nogroup. 

SEEALSO 

cfingerd(8), cfingerd . conf (5), finger(l), userlist(l), any Of the included dOCSwith thestandard cfingerd di stri buti on . 

cfingerd 1.2.1, 6 Jan 1996 
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DESCRIVO N 

The fi le /news/iib/controi.cti isused to determi ne what action istaken when a control messageisreceived. It is read by the 
parsecontroi script, which iscalled by ali thecontrol scripts. (For an explanation of how the control scripts areinvoked, see 

innd(8).) 

T hefile consists of aseriesof lines; blank linesand linesbeginningwith a number sign (#) areignored. Ali other linesconsist 
of fourfieldsseparated by a colon: 

message :from:newsgroups :acti on 

T he fi rst f ield is the nameof the message for which thislineisvalid. Itshould be either the nameof thecontrol message, or 
theword ali to mean that it is valid for ali messages. 

Thesecond fi eJ d is a shell-style pattern that matchesthee-mail addressof theperson posting the message. (Theposter's 
addressisfirst converted to lowercase.) The match ing isdone usi ng the shell's case statement; seesti(l) fordetails. 

If thecontrol message isnewgroup or rmgroup, then thethird fi eJ d specifies the shell-style pattern that must match thegroup 
bang created or removed. If thecontrol message isof a different type, then thisfield isignored. 

Thefourth field specifies what action to takeif this line is sei ected for the message. The followingactions are understood: 

doit The action requested by the control message should beperformed. In mostcases, thecontrol script 

will also send mail to Usenet. 

doifarg If thecontrol message hasan argument, thisistreated asadoit action. If no argumentwasgiven, it 

istreated asamaii entry. This isused in a sendsys entries script so that asitecan request itsown 
newsfeeds(5) entry by posting a sendsys mysite article. 0 n the other hand, sendsys bombs ask that 
thenewsfeedsfilebesent; if you use doifarg, such messages will not beprocessed automatically. 

doit=f i i e The action is performed, but a log entry iswritten to the specified log file, fi i e. If fi i e is the word 

mail, then the record ismailed. A nuli stri ng isequivalentto /dev/nuii. A pathnamethat startswith 
a slash istaken astheabsolutefilenameto use as the log. Ali other pathnamesarewritten to /var/ 

log/news/file. log. T he log iswritten bywritelog (see newslog(8)). 

drop N o action istaken; the message is ignored. 

log A one-line log noti ce is sent to standard errar, innd normally directsthisto thefile/var/iog/news/ 

errlog. 

iog=f ile A log entry iswritten to the specified log fi le, fi i e, which isinterpreted asdescribed previously. 

mail A mail messageissenttothenewsadministrator. 

Linesarematched in order; thelast match found in the fi lei s the one that isused. For example, with thefollowingthree 
lines: 

newgroup : * : * : drop 

newgroup itale?* .uu . net : comp. * ] mise. * | news. * | ree . * ] sci. * soc. * | talk. * : doit 
newgroup : kre@munnari . oz . au : aus . * : mail 

A newgroup comingfrom tale at aUUN ET machine will behonored if it isin themainstream U senet hierarchy. If kre 
posts a newgroup message creati ng aus. too, then mail will besent. Ali other newgroup messages are ignored. 

HISTORY 

Written by Ri eh $alz (rsaizuuunet.uu.net) for InterN etN ews. 
SEE ALSO 

innd(8), newsfeeds(5), scanlogs(8) 
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SYNOPSIS 

$CVSROOT/CVSROOT/commitinfo,v 

$CVSROOT/CVSROOT/cvsignore,v 

$CVSROOT/CVSROOT/cvswrappers , v 

$CVSROOT/CVSROOT/editinfo,v 

$CVSROOT/CVSROOT/history 

$CVSROOT/CVSROOT/loginfo,v 

$CVSROOT/CVSROOT/modules,v 

$CVSROOT/CVSROOT/rcsìnfo,v 

$CVSROOT/CVSROOT/taginfo,v 

DESCRIVO N 

cvs is a system for providi ng source control to hierarchical collectionsof sourcedirectories. Commandsand proceduresfor 
usi ng cvs aredescribed in cvs(l). cvs manages source repositories, the di rectories contai ni ng master copiesof the revision- 
controlied fi les, by copying particular revisionsof the fi lesto (and modificationsbackfrom) developers' private working 
di rectories. In termsof filestructure, each individuai source repository isan immediate subdirectory of $cvsroot. The fi les 
described here are supporti ng fi les; they do not haveto exist for cvs to operate, but they allow you to makecvs operation 
moreflexible. 

You can usethemoduies fileto define symbolic namesfor collectionsof source mai ntai ned with cvs. If thereisno moduies 
file, developers must specify complete pathnames(absolute or relative to $cvsroot) for the fi les they want to managewith cvs 
commands. You can usethecommitinfo fileto defineprogramsto executewhenever cvs commit isabout to execute. These 
programsareused for"precommit" checkingto verify thatthemodified, added, and removed files are reali y ready to be 
committed. Some uses for this check might beto turn off a portion (or ali) of the source repository from a particular person 
or group or perhapsto verify that the changed filesconform to the site's standards for coding practice. 

You can usethecvswrappers fileto record cvs wrapper commands to beused when checking files into and out of the 
repository. W rappers allow the fi le or directory to be processed on theway in and out of cvs. Theintended uses are many; 
one possi ble use i sto reformat a C file beforethefile is checked in so ali the code in the repository looksthesame. You can 
use the ìoginfo fileto define programsto execute after any commit, which writesa log entry for changesin the repository. 
These logging programs might beused to append the log messageto a file or send the log messagethrough electronic mail to 
a group of developers. You can also post the log messageto a particular newsgroup. 

You can use the taginfo fileto defineprogramsto execute after any tag or rtag operation. These programs might beused to 
append a messageto a file listi ng the new tag nameand theprogrammer who created it, to send mail to a group of develop- 
ers, orto post a messageto a particular newsgroup. You can usethercsinfo fileto define formsfor log messages. You can use 
theeditinfo fileto define a program to execute for editing or validating cvs commit log entries. This ismost useful when used 
with a rcsintoformsspecification becauseit can verify that the proper fieldsof theform werefilled in by the user com m it- 
ti ng the change. You can usethecvsignore fileto specify the default list of files to ignoreduring update. You can use the 
mstory fileto record the cvs commands that affect the repository. The creati on of thisfileenables hi story logging. 

FILES 

moduies The moduies fi le recordsyour defini tions of namesfor collectionsof source code. 

cvs will use these definitions if you use cvs to check in a fi le with theright 
formatto $cvsRooT/cvsRooT/moduies,v.Themoduies filecan contain blank lines 
and comments (lines beginning with #) aswell asmodule definitions. Long lines 
can be conti nued on thenext lineby specifyi ng a backslash (\) asthelast 
characteron theline A module definition isasinglelineof the moduies filein 
either of two formats. In both cases, mname represents the symbolic module name, 
and the remainder of the line is its definition. 

mna me -a a I i a s es ... 

This represents the si mplest way of defi ni ng a module mn a me . T he -a flags the 
definition asasimplealias: cvs will treat any useof mname(asacommand 
argument) asif the list of namesai i ases had been specified instead. ai i ases may 
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contai n either other modulenamesor paths. When you use paths in ai ases ,cvs 
checkout create ali i ntermediate di rectories in the working directory, just asif the 
path had been specified explicitly in thecvs arguments. 

mname [ opti o n s ] dir [ files ... ] [ &mo d j I e ...] 

In thesimplest case, thisform of module definition reducesto mname di r . T his 
defines ali thefilesin directory di r as module mname. di r is a relative path (from 
$cvsroot) to a directory of sourcein oneof thesourcerepositories. In thiscase, 
on checkout, a single directory called mname iscreated as a working directory; no 
i nterm ed i ate d i rectory levelsareused by default, even ifdir wasapath involving 
several directory levels. By explicitly specifying files in the module definition after 
dir, you can sei ect parti cui ar files from directory di r . T he sample definition for 
modules isan exampleof a module defi ned with a single fi le from a parti cular 
directory. H ere isanother example 

m4test unsupported/gnu/m4 foreach.m4 forloop.m4 

With this definition, executing cvs checkout m4test will create a single working 
directory m4test contai ni ng the two files listed, which both comefrom a 
common directory several levels deep in thecvs sourcerepository. A module 
definition can referto other modules by including&modu e in its definition. The 
checkout command creates a subdirectory for each such module in your working 
directory. New in cvs 1.3; avoid thisfeatureif sharing module definitions with 
older versionsof cvs. 

Finally, you can useoneor moreof thefollowingoptionsin module definitions: 
-d n a me namestheworki ng directory something other than the module name. 
Thisoption is new in cvs 1.3; avoid thisfeature if sharing module definitions 
with older versionsof cvs. -t prog allowsyou to specify a program prog to run 
whenever files in a module are committed. prog runswith asingleargument, the 
full pathnameof the affected directory in a sourcerepository. Thecommitinfo, 
ìoginfo, and editinto fi les provi de other waysto cali a program on commit. -o 
prog allowsyou to specify a program prog to run whenever fi les in a module are 
checked out. prog runswith asingleargument, the module name. -e prog allows 
you to specify a program prog to run whenever files in a module are exported. 
prog runswith asingleargument, the module name. -t prog allowsyou to 
specify a program prog to run whenever filesin a module are tagged. prog runs 
with two arguments: the module name and the symbolic tag specified to rtag. -u 
prog allowsyou to specify a program prog to run whenever cvs update isexecuted 
from thetop-level directory of the checked-out module. prog runswith a single 
argument, the full path to the sourcerepository for this module. 
commitinfo, ìoginfo, rcsinto, editinto Thesefiles ali specify programsto cali at different points in thecvs commit 

process. They have a common structure. Each lineisa pair of fields: a regular 
expression, separated by whitespacefrom afilenameorcommand-linetemplate. 
W henever one of the regular expression matches a directory name in the 
repository, therest of the line isused. If the line begins with a# character, the 
enti re line isconsidered acomment and isignored. Whitespace between the 
fields i salso ignored. For ìoginfo, therest of the lineisa command-linetemplate 
toexecute. Thetemplatescan include notonly a program name, butalso 
whatever list of arguments you want. If you write %s somewhereon the argument 
list, cvs supplies, atthat point, thelistof files affected by thecommit. Thefirst 
entry in the list isthe relative path within thesource repository where the change 
is being made. The remai ni ng arguments list the fi les that are being modified, 
added, or removed by this commit invocation. Fortaginfo, therest of the line is 
acommand-linetemplateto execute. The arguments passed to the command are, 
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i n Order, thetagname, operati on (add for tag, mov for tag -F, and del for tag -d), 

and reposi tory, and any remaining are pai rs of filename revision. A nonzero exit 
of the fi Iter program will cause the tag to beaborted. For commitinf o, therest of 
thelineisacommand-linetemplateto execute. Thetemplatecan include not 
only a program name but also whatever list of argumentsyou want. The full path 
to thecurrent sourcerepository isappended to thetemplate, followed by the 
filenamesof anyfilesinvolved in thecommit(added, removed, and modified 
files). For rcsinfo, therest of the line is the full path to afilethat should be 
loaded into the log messagetem piate. Foreditinfo, therest of the line is a 
comm an d- 1 i n e tem pi ate to execute Thetemplatecanincludenotonlya 
program name but also whatever list of argumentsyou want. Thefull path to the 
current log messagetem pi ate fi le isappended to thetemplate. You can useoneof 
two special stringsinstead of a regular expression: all specifiesacommand-line 
templatethat must always beexecuted, and default specifiesacommand-line 
templateto useif no regular expression is a match. The commitinf o fi le contai ns 
commandsto execute before any other commit activity, to allow you to check 
any conditions that must be satisfied before commit can proceed. T he rest of the 
commit will execute only if all selected commandsfrom thisfileexitwith exit 
status 0. The rcsinfo fileallowsyou to specify log templates for the commit 
logging session; you can usethisto provi deaform to editwhen fillingoutthe 
commit log. T he fieJd after the regular expression, in thisfile, contai ns fi lenames 
(of files containingtheloggingforms) ratherthan command templates. The 
editinf o fi le allows you to execute a script before the commit starts but after the 
log information isrecorded. These"edit" seri pts can verify information recorded 
in thelogfile If theedit seri pt exits with a nonzero exit status, thecommit is 
aborted. Theioginfo filecontainscommandsto execute at the end of acommit. 
Thetext speci fi ed as a commit log messageispiped through the command; 
typical uses include sending mail, filingan articlein anewsgroup, orappending 
to a centrai file. 

cvsignore, .cvsignore T he default list of files (or sn(l) fi lename patterns) to ignore during cvs update. 

At startup ti me, cvs loadsthecompiled default list of filename patterns (see 
cvs(l)). Then theper-repository list included in $cvsR00T/cvsR0OT/cvsignore is 
loaded, if itexists. 

Then theper-user list is loaded from $home/. cvsignore. Finally, ascvs traverses 
through you r di recto ri es, itwill load any per-directory .cvsignore files whenever 
it finds one. These per-directory files are only valid for exactly the directory that 
contai nsthem, not for any subdirectories. 
nistory C reate thisfile in $cvsroot/cvsroot to enable history logging (see the descri ption 

Of cvs history). 

SEE ALSO 

CvS(l) 

COPYING 

Copyright ® 1992, CygnusSupport, Brian Berliner, and Jeff Polk. 

Permission isgranted to makeand distribute verbatim copiesof thismanual, provi ded the copyright noticeand this 
permission noticearepreserved on all copies. 

Permission isgranted to copy and distribute modified versi onsof thismanual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to this one. 
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Permission is granted to copy and distri butetranslationsof thismanual into another language, under the precedi ng 
conditionsfor modified versions, exceptthatthis permission noticemay beincluded in translationsapproved by theFree 
Software Foundation instead of in the originai English. 

12 February 1992 
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devinfo — D evice entry database. 
DESCRIPTION 

devinfo is a text fi le that describes ali the possi bledevicesfor a system. It isused by makedev(8) to create special fileentriesin / 
dev. It may benamed either /dev/DEviNFo or /etc/devinfo. Information about custom locai devices, if any, should beplaced 
in devinfo. locai or /etc/devinfo. locai, which has the same syntax. 

Thefileformat isfree-form. C, C++, and shell commmtsareunderstood.There are basicallyfour statement?: 

ignot-e { proc-devi ce ... } T his causes the specified names to be ignored if found in /proc/devices. 

batch { device... } T his creates a "batch"— a collection of devices that wi II ali be created when the batch is 

invoked. Forexample, in the standard devinfo, "generic" isa batch, 
block devi ce- s p e c This defines one or more block devices. 

char devi c e - s p e c T his defines one or more character devices. 

H ere is a sample dev c e - s p e c : 

(std, 1) { 
mera (kmem) : 1 
nuli (public) : 3 
core -> "/proc/kcore" 
} 

T his example defines a group of devices called std, with major number 1. Running will create ali the devices in thegroup; 
running, for example, would make just the one device nuli. 

It is possi bleto specify, instead of just std, something like std=foo. In this case, the stuff on theright-hand side of the equals 
sign specifiesanamefrom /proc/devices, and the major number will beretrieved from thereif present. If an entry from / 
proc/devices isspecified, the explicit major number may beomitted. In this case, if the number isnot found in /proc/ 
devices, attemptsto create thedevice will be rejected. 

I nside the braces isa list of specific devices. The name in parenthesisis the "class"; this is something specified in MAKEDEv.ctg 
that determi nes the ownership and permissionsof the special fi le created. In the precedi ng example, the device meni wasset to 
have the class kmem, but nuli wasset to be public. 0 rdinarily, you'd define public to be mode 666 but kmem to be mode 660 
and owned by group kmem. The number after the colon is the minor number for this particular devi ce; for instance, 3 for 

nuli. 

You may also specify a symbol ic link with ->. For instance, core was madea link to /proc/kcore. N otethat names may 
contain any characters, but names that co ntain thingsotherthan alphanumerics, dash, and underscore should beputin 
doublé quotes. 

An enti re range of devices can be created. You may specify a range of numbers in brackets: 

tty[1-8] (tty) : 1 

T his creates ttyi-tty8 with minor device numbers starti ng with 1. If you specify the range in hex(prefixed by ex), thedevice 
names will be created numbered in hex, asisnormal for ptys. The range may appear i nside the name stri ng, but theremay 
only beone range. 
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There is a special syntax for creati ng the enti re banks of devicesfor a hard drive: 
hd[a-d] 8/64 

What thismeans isasfollows: Create hda, and eight partitionson hda (hdai through hdas), starti ng with minor number 0. 
Then create hdb, and eight parti tions, starti ng with minor number 64. Then hdc, and so on, with minor number 64*2 = 
128— and so forth. These are automati cai ly placed in the class disk. The necessary groupsand batch es are created so you can 
ask makedev to create hd or hda or hdai and expect itto do thecorrect thing. 

N otethat si mple arithmetic ispermitted for specifying the minor device number, asthisoften makesthingsmuch clearer 
and lesslikelyto be accidentally broken. 

SEEALSO 

MAKEDEV(8), MAKEDEV. cfg(5) 

Verson 1.4, January 1995 



environ 

environ— U ser environment. 
SYNOPSIS 

extern c h a r **e n v i r o n ; 

D ESC RIPTIO N 

An array of stri ngs cali ed the e n vi ronment ismadeavailableby exec(2) when a process begins. By convention, these stri ngs 
havetheform n a me =v a uè. Common examplesare 



user Thenameof thelogged-in user(used by some BSD -derived programs). 

logname Thenameof thelogged-in user(used by someSystem-V derived programs). 

home A user'slogin directory, set by ìogin(l) from the password file passwd(5). 

lang Thenameof alocaleto use forlocalecategories when notoverridden by lc_all or more 

specific environment variables. 

path T he sequenceof directory prefixesthat sh(l) and many other programs apply in searching 

forafileknown by an incomplete pathname. The prefixes are separated by :. 
shell Thefilenameof theuser's login shell. 

term Theterminal typeforwhich output isto beprepared. 



Further namesmaybe placed in the environment by the export command and name=vai ue in sn(l) or by thesetenv command 
if you usecsh(l). Argumentsmay al so be placed in the envi ronment at the poi nt of an exec(2). 

It isrisky practiceto set nane =v a i ue pairsthat conflict with well-known shell variables. Setti ng these could cause surprising 
behavior in subshellsorsystem(3) commands. 

SEEALSO 

login(l), sh(l), bash(l), csh(l), tcsh(l), exec(2), system(3) 

Linux, 21 October 1996 



expire. ctl 

expire. cti— Control file for U senet article expiration. 
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DESCRIVO N 

The fi le /news/iib/expire.cti is the default control filefortheexpire(8) program, which readsit at startup. Blank linesand 
lines beginning with a number sign (#) areignored. AH other linesshould bein oneof two formats. 

The first format specifies how longto keep a record of fui ly expired articles. Thisisuseful when a newsfeed intermittently 
offersolder newsthat isnot kept around very long. (The case of very old news is handled by the-c flag of innd(8).) There 
should only beone li ne in this format, which looks likethis: 

/remember/ : d a y s 

Wheredays is a floati ng-point number that specifies the upper limitto remember a M essage-ID, even if the article has 
al ready expired. (It does not affect article expirations.) 

M ost of the lines in the file wi II consist of fivecolon-separated fields, asfollows: 

pattern : mo d f I ag : k e e p : d e f a u I t : p u r g e 

The pattern field iscomma-separated set of single wiidmat(3)-stylepatterns that specify the newsgroupsto which the rest of 
thelineapplies. Becausethefileisinterpreted in order, the most general patterns should bespecified first, and themost 
specific patterns should bespecified last. 

Themodf i ag field can beused to further I i mi t newsgroupsto which thelineapplies and should bechosen from thefollowing 
set: 

m Only moderated groups 

u 0 nly unmoderated groups 

a Ali groups 

T he nextthree fields are used to determine how long an article should bekept. Each field should beeither a number of days 
(fractionssuch ass.5 areallowed) or the word never. Themost common use i sto specify the default valuefor how long an 
article should bekept. The first and third fields— keep and purge — specify the boundarieswithin which an Expiresheader 
will behonored. They areignored if an article has no Expiresheader. The fields are specified in thefileas"lower-bound 
default upper-bound," and they areexplained in this order. Becausemost articles do not haveexplicit expiration dates, 
however, thesecond field tendsto be the most important one. 

The keep field specifies how many daysan arti eie should bekept before it wi 1 1 beremoved. N o article in the newsgroup will 
beremoved if it hasbeen filed for lessthan keep days, regardlessof any expiration date. If thisfidd istheword never, then an 
article cannot havebeen kept for enough days so it will never be expired. 

The def au 1 1 field specifies how longto keep an article if no Expires header is present. If this field istheword never, then 
arti ci es wi thout expl i ci t expi rati on dates wi 1 1 never be expi red . 

The purge field specifies the upper bound on how long an article can bekept. N o article will bekept longer than the number 
of days specified by thisfield. AH articles will beremoved after they havebeen kept forpur ge days. If purge istheword never, 
then the article will never bedeleted. 

It isoften useful to honor the expiration headers in articles, especi ally thosein moderated groups. To do this, set keep to zero, 
def ani t to whatever value you want, and pur ge to never. To ignoreany Expires header, set ali th ree fieldsto thesamevalue. 

There must beexactly one li ne with a pattern of * and a modf i ags of a; this matches ali groups and isused to set the 
expiration default. It should bethefirst expiration line Forexample: 

## How long to keep expired history 
/remember/ : 5 

## Most things stay for two weeks 
:A: 14: 14: 14 

## Believe expiration dates in moderated groups, up to six weeks 
:M:1 :30:42 

## Keep locai stuff for a long time 
foo.*:A:30:30:30 



exports 



1123 



HI STORY 

W ritten by Rich $alz (rsaiz@uunet. uu.net) for InterN etN ews. 
SEEALSO 

expire(8), wildmat(3) 

exports 

exports— N FS filesystems being exported. 
SYNOPSIS 

/etc/exports 

D ESC RIFTIO N 

Thefile /etc/exports serves as the access control list for filesystems that can be exported to N FS cliente. It isused by both the 
N FS mount daemon mountd(8) and the N FS fi le server daemon nfsd(8). 

The fi le format issimilarto the SunOS exports file, except that several additional options are perni itt ed. Each li ne contai ns a 
mount poi nt and a list of machine or netgroup namesallowed to mount the fi lesystem at that point. An optional parenthe- 
sized list of mount parameters may follow each machine name. Blank linesareignored, and a# introducesacomment to the 
end of the li ne. 

GENERAL OPTIONS 

secure Thisoption requiresthat requests ori gi nate on an Internet port lessthan ipport_reserved 

(1024). Thisoption ison by default. To turn it off, specify insecure. 

ro Allow only read-only requests on thisN FS volume. The default isto allow write requests as 

well, which can also bemadeexplicit by usingtherwoption. 

iink_reiative Convert absolute symbol ic links (where the link contente start with a slash) into relative 

links by prependi ng the necessary number of . ./sto get from the directory contai ning the 
link to theroot on the server. T hi shassubtle, perhaps questi onable, semanticswhen thefile 
hierarchy isnot mounted at itsroot. 

iink_absoiute Leaveall symbolic links as they are. This is the default operation. 

USERID MAPPING 

ntsd bases ite access control to fileson theserver machineon theU ID andGID provided in each N FS RPC request.The 
normal behavior a user would expect is that she can access her fileson theserver just asshewould on a normal fi lesystem. 
This requiresthat the sameU IDs and GIDsareused on theclient and theserver machine This isnot alwaystrue, nor isit 
alwaysdesi rable. 

Very often, it is not desi rable that theroot user on aclient machine is also treated asrootwhen accessi ng fileson theN FS 
server. To this end, UID 0 isnormally mapped to adifferent ID : the so-called anonymousor nobody UID . This mode of 
operation (called rootsquashing) isthe default and can beturned off with no_root_squasn. 

By default, ntsd triesto obtain theanonymousU ID and GID by lookingup user nobody in the password fileat startup 
ti me. If it isn'tfound, aU ID and GID of -2 (65534) isused. Thesevalues can also beoverridden by theanonuid and anongid 
options. 

In additi on to this ntsd letsyou specify arbitrary U IDs and GID s that should be mapped to user nobody as well. Finally, 
youcan mapall user requests to theanonymousU ID by specifyingtheaii_squasn option. 

For the benefit of installations where U IDsdiffer between different machines, ntsd providesaway to dynamically map server 
U IDs to client U IDs and viceversa. This isenabled with the map daemon option and usestheuGiD RPC protocol. For this 
to work, you haveto run theugidd(8) mapping daemon on theclient host. 
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H ere's the complete list of mappi ng options: 



root_squash 

no_root_squash 
squash_uids and squash_gids 



all_squash 



map_daemon 



anonuid and anongid 



EXAMPLE 



M ap requests from U ID/GID 0 to theanonymousU ID/GID . N otethat thisdoes not 

apply to any other U IDsthat might beequally sensitive, sudi asuser bin. 

Turn off root squashing. Thisoption ismainly useful for diskless clients. 

Thisoption specifiesa list ofUIDsor G IDsthat should besubjectto anonymousmapping. 

A valid listof IDslookslikethis: 

squash_uids=0-15,20,25-50 

Usually, your squash listswill look a lotsimpler, such as 

squash_uids=0 - 100 

M ap ali U IDsand GIDsto the anonymous user. U seful for N FS-exported public FTP 
directories, newsspool directories, and so on. Theoppositeoption isno_aii_squash, which is 
the default setti ng. 

Thisoption turnson dynamic U ID/GID mappi ng. Each U ID in an N FS request will be 
translated to the equi valent server U ID, and each U ID in an N FS reply will bemapped the 
other way round. Thisoption requiresthat rpc.ugidd(8) runson the client host. T he default 
setting ismapjdentity, which leaves ali UID suntouched. Thenormal squash options apply 
regardlessof whether dynamic mappi ng isrequested. 

These options explicitly set theUID and GID of the anonymous account. Thisoption is 
primarily useful for PC/N FS clients, whereyou might want ali requests appear to befrom 
oneuser. Asan example, consider the export entry for /home/joe in thesection "Example," 
which mapsall requests to UID 150 (which issupposedly that of user joe). 



# sample /etc/exports file 

/ master(rw) trusty(rw,no_root_squash) 

/ prò j ects prò j * . locai . domain ( rw) 

/usr *. locai. domain(ro) @trusted(rw) 

/home/joe pc001 (rw,all_squash,anonuid=150,anongid=100) 

/pub (ro,insecure,all_squash) 

Thefirst line exports the entire filesystem to machines master and trusty. In addition to write access, ali UID squashing is 
turned off for host trusty. The second and third entry show examplesforwildcard hostnamesand netgroups (this isthe 
entry Mrusted). The fourth line shows the entry for the PC/N FS client discusseci previ ously. The last li ne exports the public 
FTP directory to every host in theworld, executing ali requests under the nobody account. Theinsecure option in this entry 
also allows clients with N FS implementations that don't use a reserved port for NFS. 

CAVEATS 

U nlike other N FS server implementations, thisntsd allowsyou to export both a directory and a subdirectory thereof to the 
samehost, for instance/usr and /usr/xnR6. In this case, themount options of the most specific entry apply. For instance, 
when a user on the client host accessesafilein /usr/xnR6, themount options given in the/usr/xnR6 entry apply. This is 
also truewhen the latter isawildcard or netgroup entry. 



FILES 

/etc/exports 
/etc/passwd 



Configuration file for nf sd{8) 
The password file 



DIAGNOSTICS 

An errar parsingthefile is reported usi ng sysiogd(8) as leve! notice from bdaemon whenever ntsd(8) or mountd(8) is started. 
Any unknown host is reported at that time, but often not ali hostsarenotyet known to named(8) at boot time, so ashostsare 
found, they are reported with thesamesysiogd(8) parameters. 



fi lesystems 
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SEEALSO 

mountd(8), nfsd(8), nfs(5), passwd(5) 



21 October 1996 



filesystems 



filesystems — Linux fi lesystem types: minix, ext, ext2, xia, msdos, umsdos, vfat, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs. 



D ESC RIPTIO N 

In the fi le /p 
unsupported 

Following isa description of the various filesystems. 



roc/fiiesystems, you can fi nd which fi lesystems your kernel currently supports. (If you need acurrently 
one, i nsert the correspondi ng module or recompi le the kernel .) 



ext 



ext2 



xiaf s 

msdos 

umsdos 

vfat 

proc 

iso9660 
High Sierra 

Rock Ridge 

hpfs 
sysv 
nfs 



The fi lesystem used in the M inix operati ng system, thefirstto run under Linux. It hasa number 
of shortcomings: a64M B partition sizelimit, short fi lenames, a single ti me stamp, and so on. It 
remainsuseful for floppies and RAM disks. 

An elaborate extension of theminix filesystem. It hasbeen completely superseded bythesecond 
version of theextended filesystem (ext2) and will eventually beremoved from the kernel. 
Thehigh performance disk filesystem used by Linux forfixed disks aswell asremovable media. 
Thesecond extended filesystem wasdesigned asan extension of theextended filesystem (ext). 
ext2 offers the best performance (in termsof speed and CPU usage) of the filesystems supported 
under Linux. 

Designed and implemented to beastable, safe fi lesystem by extendingtheM inix filesystem code. 
It provides the basic, most requested featureswithout unduecomplexity. The xia filesystem is no 
longer actively developed or maintained. It isused i nf requently. 

Thefilesystem used by DOS, Windows, and someOS/2 computerà msdos filenamescan beno 
longer than an eight-character namefollowed by an optional period and three-character 
extension. 

An extended DOSfilesystem used by Linux. It adds capability for long filenames, UID/GID, 
POSIX permissions, and special files(devices, named pipes, and so on) under theDOS 
filesystem, without sacrifici ng compati bility with DOS. 

Extended DOSfilesystem used by M icrosoft W indows95 and Windows NT. vfat adds 
capability for long filenames under the MS-DOS filesystem. 

A pseudo-fi lesystem that is used as an i nterface to kernel data structures rather than readi ng and 
interpreting /dev/kmem. In particular, itsfilesdo nottakedisk space. Seeproc(5). 
A CD-ROM filesystem typeconformingto the ISO 9660 standard. 

Linux supports H igh Sierra, theprecursorto the ISO 9660 standard for CD-ROM filesystems. It 
isautomatically recognized within theiso9660 filesystem support under Linux. 
Linux also supports theSystem Use Sharing Protocol records specified by the Rock Ridge 
Interchange Protocol. They are used to further descri be the files in theiso9660 filesystem to a 
UNIX host and provides information such as long fi lenames, UID/GID, PO SIX permissions, 
and devices. It isautomatically recognized within theiso9660 filesystem support under Linux. 
TheH igh Performance Fi lesystem, used in OS/2. This fi lesystem isread-only under Linux dueto 
thelack of availabledocumentation. 

An implementation of the SystemV/Coherent fi lesystem for Linux. It implementsall Xenix FS, 
SystemV/386 FS, and C oherent FS. 

Thenetwork filesystem used to access disks locatedon remote co mputers. 
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smb A network filesystem that supportstheSM B protocol, used by Windows for W orkgroups, 

WindowsNT, and LAN Manager. 

To use smb, you need a special mount program, which can befound in theksmbfs package at 
ftp://sunsite.unc.edu/pub/Linux/system/Filesystems/smbfs. 
ncpfs A network filesystem that supportsthe N C P protocol, used by N ovell N etW are 

To use ncpfs, you need special programsfound atftp://iinuxai .gwdg.de/pub/ncpfs. 

SEEALSO 

proc(5), f sck(8), mkf s(8), mount(8) 

25 M arch 1996 



fstab 

fstab— Static information about thefilesystems. 
SYNOPSIS 

#include <fstab.h> 

D ESC RIPTIO N 

The fi le fstab contai nsdescripti ve information about thevariousfilesystems. fstab isonly read by programsand notwritten; 
it istheduty of the system administratorto properly create and maintain thisfile. Each filesystem isdescribed on a separate 
line fieldson each line are separated by tabsor spaces. Theorder of recordsin fstab isimportant becausefsck(8), mount(8), 
and umount(8) sequentially iterate through fstab doingtheir thing. 

The first field (fs_spec) describes the block special device or remote filesystem to bemounted. 

Thesecond field (fs_fiie) describes the mount point for the filesystem. For swap partiti ons, this field should bespecified as 

none. 

T he third field (fs_vfstype) describes the type of the filesystem. The system currently supports threetypes of filesystems: 



minix 


A locai filesystem, supporti ng fi lenamesof length 14 or 30 characters. 


ext 


A locai filesystem with longer filenamesand larger inodes. This filesystem hasbeen replaced 




by theext2 filesystem and should no longer beused. 


ext2 


A locai filesystem with longer fi lenames, larger inodes, and a lot of otherfeatures. 


xiaf s 


A locai filesystem with longer fi lenames, larger inodes, and a lot of otherfeatures. 


msdos 


A locai filesystem for M S-DOS partitions. 


hpfs 


A locai filesystem for H PFS partitions. 


iso9660 


A locai filesystem used for CD -ROM drives. 


nf s 


A filesystem for mounting parti ti ons from remote system s. 


swap 


A disk partition to beused forswapping. 



If vfs_fstype isspecified asignore, the entry is ignored. Thisisuseful to show disk partitions that are currently unused. 
Thefourth field (fs_mntops) describes the mount options associateci with the filesystem. 

It isformatted asacomma-separated list of options. It contai ns at least the type of mount plusany additional options 
appropri ateto the filesystem type. For documentation on the available optionsfor non-N FS filesystems, seemount(8). For 
documentation on ali N FS-specific options, takea look atnfs(5). Common for ali typesof filesystemsaretheoptionsnoauto 
(do not mount when mount -a isgiven, such asat boottime) and user (allow a user to mount). For more details, seemount(8). 

Thefifth field (fs_freq) isused for these filesystems by thedump(8) command to determi ne which filesystems need to be 
dumped. If thefifth field isnot present, avalueof zero isreturned and dump will assume that the filesystem doesnot need to 
be dumped. 



groff_ font 




Thesixth field (fs_passno) isused by thefsck(8) program to determinetheorder in which filesystem checksaredoneat 
reboottime. T he root filesystem should bespecified with atsjassno of 1, and other filesystemsshould haveafs_passno of 2. 
Filesystemswithin adrivewill bechecked sequentially, butfilesystemson different drives will bechecked atthesametimeto 
utilize parai lelism available in the hardware. If thesixth field isnot present orzerò, a valueof zero isreturned and fsck will 
assume that the filesystem doesnot need to bechecked. 

Theproper way to read recordsfrom fstab isto usetheroutinegetmntent(3). 

FILES 

/etc/fstab 

BUGS 

Thedocumentation in mount(8) isoften more up-to-date 
SEEALSO 

getmntent(3), mount(8), swapon(8), nf s(5) 

HISTORY 

The fstab fi le format appeared in 4.0 BSD . 

Linux 0.99, 27 N ovember 1993 
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groff_font— Format of groff devi ce and font description files. 
DESCRIPTION 

The groff _font format isroughly asuperset of theditroff font format. U nliketheditroff font format, thereisno associ ated 
binary format. The font files for device n a me arestored in a directory devname. Therearetwo typesof file: a devi ce description 
filecalled desc and for each font f, a font file called f. These are text files; thereis no associateci binary format. 

DESC FILE FORMAT 

The desc filecan contain the following typesof lines: 

Therearen machine units per inch. 
Thehorizontal resolution isn machineunits. 
Thevertical resolution isn machineunits. 

The scale factor for pointsizes. By default, thishasa valueof 1. 0 nescaled point is 
equal to one point/n . Theargumentsto the unitwidth and sizes commandsare 
given in scaled points. 

Q uantiti es i n the font fi les are given i n machi ne units for fonts whose point size is n 
scaled points. 

T hismeans that the postprocessor can handlethet and u output commands. 
sn0 This means that the devi ce has fonts atsi, s2,... sn scaled points. The list of sizes 

must be termi nated by ao. Each si can also bea rangeof sizes m-n. The list can 
extend over morethan one line, 
styies si S2 ... sm T hefirst m font positions will be associated with styles si ... sm. 

fonts n fi F2 F3 ... Fn Fonts fi ... Fn wi II be mounted in thefont positionsm+1,... ,m+n where m isthe 

number of styles. This command may extend over morethan one line. A font name 
of 0 will cause no font to be mounted on thecorresponding font position. 



res n 
hor n 
vert n 
sizescale n 



unitwidth n 



tcommand 
sizes s1 s2 
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famiiy f a m T he default font family iSf a m. 

charset T his li ne and everyth i n g f o 1 1 ovvi n g in thefile are ignored. It is allowed forthesakeof 

backwards compati bility. 

Theres, unitwidth, fonts, and sizes lines are compulsory. Other commands are ignored by troff but may beused by 
postprocessorsto store arbitrary information about the device in the desc file. 

FONT FILE FORMAT 

A font filehastwo sections. The first section isa sequenceof lines, each contai ni ng a sequenceof blank delimited words; the 
first word in the line isa key, and subsequent words givea valueforthat key. 

name f T he name of the font is f . 

spacewidth n The normal width of a space isn . 

siant n T he characters of the font have a slant of n degrees. (Positive meansforward.) 

ìigatures ligi iig2 ... ìign [0] C haracters ligi , iig2,... ,iign are I i gatu res; possi ble ligatures are f f , f i, f 1, and f f 1. 

For backwards com pati bility, the list of ligatures may beterminated with a e. The 
list of ligatures may not extend over morethan oneline. 

special Thefont is special; this meansthat when a character isrequested that isnot present 

in the current font, it will besearched for in any special fonts that are mounted. 

Other commands are ignored by troff but may beused by postprocessorsto store arbitrary information about thefont in the 
font file. 

The first section can contai n comments, which start with the # character and extend to the end of a line. 

Thesecond section contai nsone or two subsections. It must contain a charset subsection and it may also contain a kernpairs 
subsection. These subsections can appear in any order. Each subsection startswith a word on a lineby itself. 

The word charset startsthe charset subsection. The charset lineisfollowed by a sequenceof lines. Each linegives 
information for one character. A linecomprisesa number of fi el ds separated by blanksor tabs. The format is 

na me me t r i c s t y pe code c o mine nt 

name identifies the character: if name isa single character c, it correspondsto thegroff input character c; if it isof theform \c 
wherec isa single character, then it correspondsto thegroff input character ne; otherwise, it correspondsto thegroff input 
character \ [nane ] (if it isexactly two charactersxx, it can beentered as\(xx ). groff supports eight-bit characters; however, 
some utilities have difficulties with eight-bit characters For this reason, there isa convention that the name charn is 
equivalent to the single character whose code isn. Forexample, chan63 i s equi valentto the character with codel63, which is 
the pounds sterling sign in ISO Latin-1. The name— is special and indicates that the character isunnamed; such characters 
can only beused by meansof the\N escape sequence in troff. 

Thetype field gives the character type: 

1 The character hasan descender, such asp. 

2 T he character hasan ascender, such asb. 

3 The character hasboth an ascender and a descender, such as (. 

The code field gives the code that the postprocessor usesto print the character. The character can also be input to groff using 
thiscodeby meansof the \n escape sequence. The code can be any i nteger. If it startswith a 0, it will beinterpreted asoctal; 
if it startswith ©x or ox, it wi II beinterpreted ashexadecimal. 

Anything on the li ne after the code field will be ignored. 

T he met r cs field has theform: 

width[ ,height[ ,depth[ , italic_correction[ , left_italic_correction 
»[ ,subs c r i pt _ c 0 r r ed i on ] ] ] ] ] 

There must not be any spaces between these su bf i el ds. M issingsubfieldsareassumed to beo. T he subfi elds are ali decimai 
integers. Becausethereisno associated binary format, these values are not required to fit into a variableof typechar asthey 
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are in ditroff.Thewi dth subfidds givesthewidth of the character. T he hei g h t subfield gives the height of the character 
(upwardsis positive); if a character does not extend abovethebaseline, itshould begiven azero height, ratherthan a negative 
height. The de pt h subfield gives the depth of the character, that is, thedistancebelow thelowest point below the baseli ne to 
which the character extends(downwardsis positive); if a character does not extend below abovethebaseline, it should be 
given azero depth, ratherthan a negative depth. The tal i c_ cor recti on subfield givestheamount of space that should be 
added after the character when it is immediately to befollowed by a character from a roman font. The 
i e f t _ i tal ì c _ c o r recti on subfield gives the amount of space that should be added before the character when it is immediately 
to bepreceded by a character from a roman font. Thesubscript_correction givestheamount of space that should be added 
after a character before addi ng a subscript. This should belessthan the i tal i c _ c o r recti on. 

A line in thecharset section can also have the format 

n a me " 

This indicates that name i sjust another name for the character menti oned in the precedi ng line. 
The word kernpairs startsthekernpairs section. T his contai ns a sequence of linesof theform: 

d c2 n 

T his means that when character ci appears next to character c2, the space between them should beincreased by n. M ost 
entri es in kernpairs section will have a negative value for n. 

FILES 

/usr/iib/groff /font/dev name/DEsc D evi ce descri ption fi le for device name. 
/usr/iib/groff/font/devname/F Font fi le for font f of device name. 



SEE ALSO 

groff_out(5), gtroff(l) 

G roff V ersi on 1.09, 14 February 1994 



groff_out 

groff_out— groff intermediate output format. 
DESCRI PTION 

Thismanual page descri bes the format output byGNU troff. The output format used byGNU troff is very similar to that 
used byUNIX device-independent troff . Only thedifferencesaredocumented here. 

Theargumentto thes command isin scaled points(unitsof poi nts/n , wheren istheargumentto thesizescaie command in 
theDEsc file.) Theargumentto thex H eight command is also in scaled points. 

The fi rstthree output commands are guaranteed to be 

x T device 
x res n h v 
x init 

If thetcommand line ispresent in theDEsc file troff will usethefollowing two commands: 

txxx xxx isany sequence of charactersterminated byaspaceoranewline; thefirst 

character should beprinted at the current positi on, thecurrent horizontal position 
should beincreased by thewidth of thefirst character, and so on for each character. 
Thewidth of the character is that given in the font file appropri ately scaled for the 
current point sizeand rounded so that it is a multiple of the horizontal resolution. 
Special characterscannot beprinted using this command. 
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unxxx Thisissameasthet command exceptthat after printing each character, thecurrent 

horizontal position isincreased by thesum of thewidth of that character and n. 

N otethat single characters can havethe eighth bit set, ascan thenamesof fontsand special characters. 

Thenamesof characters and fontscan beof arbitrary length; driversshould not assume that they wi II beonly two characters 
long. 

When a character isto beprinted, that character wi II always bein thecurrent font. U nlike devi ce-independent troff, it isnot 
necessaryf or d ri versta search special fontsto find a character. 

T he d drawing command hasbeen extended. Theseextensionswill not beused by GN U pie if the-n option isgiven. 

Df n\n Set the shade of grayto beused forfilling solid objectston; n must bean integer 

between 0 and 1000, whereO correspondsto solid whiteand 1000 to solid black and 
valuesin between correspond to intermediateshadesof gray. Thisappliesonly to 
solid circles, solid ellipses, and solid polygons. By default, a leve! of 1000 will be 
used. W hatever color a solid object has, it should completely obscureeverything 
beneath it. A valuegreater than 1000 or lessthan 0 can also beused: Thismeans fi II 
with the shade of gray that iscurrently béng used for linesand text. N ormai ly, this 
will be black, but some driversmay provide a way of changing this 

dc d\n D raw a solid circlewith adiameter of d with the leftmost pointat thecurrent 

position. 

de dx d y \ n D raw a solid eli ipse with a horizontal diameter of dx and averti cai diameter of dy 

with the leftmost point at thecurrent position. 
Dp dxi dyi d x 2 d y 2 ... dxn dyn\n D raw a polygon with, for i = 1, n +1, the i th vertex at the current position + 

L'^ifdxi , dyj ). At the moment, GNU pie only uses this command to generate 

trianglesand rectangles. 

dp dxi dyi d x 2 d y 2 ... dxn dyn\n Like Dp, but draw a solid rather than outlined polygon. 

Dt n\n Set the current line thickness to n machine units. T raditionally, UNIX troff drivers 

use a linethickness proporti onal to thecurrent point size; driversshould conti nueto 
do this if no Dt command has been gi ven or if a Dt command has been given with a 
negative vai ueof n. A zero valueof n selects the smallest available linethickness. 

A difficulty arises in how thecurrent position should bechanged after the execution of thesecommands. This isnot of great 
importancebecause the code generated by GN U pie does not depend on this. Given a drawing command of theform 

\Dc x 1 y 1 x 2 y 2 ... x n y n 

wherec isnot oneof c, e, I, a, or ~, U N IX troff will treat each of the x i as a horizontal quantity and each of they i asa 
vertical quantity and will assume that thewidth of thedrawn object isLli x and that the height isLti yi ■ (The 
assumption about the height can beseen by examining the stand sb regi sters after usi ng such a D command in a\w escape 
sequence.) This mie also holdsfor ali the originai drawing commands with theexception of De. Forthesakeof compati bi I- 
ity, GNU troff also fol lows this rule, even though it producesan ugly result in the case of the D f, Dt, and, to a lesser extent, 
DE commands. Thus after executingaD command of theform 

De xl yl x2 y2 ... xn yn \n 

thecurrent position should beincreased by £°=i *i ; E"=i y )■ 

A conti nuation convention permitstheargument to thex X command to contai n newlines: when outputting theargument 
to thex X command, GNU troff will follow each newlinein theargument with a + character (as usuai, itwill termi nate the 
entireargumentwith a newline); thusif the line after the line containing the x X command starts with +, then thenewline 
ending the line contai ni ng thex X command should betreated aspart of theargument to thex X command, the+ should be 
ignored, and the part of the li ne fol lowing the + should betreated like the part of the li nefollowing the x X command. 



SEEALSO 

groff_font(5) 



hi story 



FI 
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group 

group— U ser group fi le. 
D ESC RIPTIO N 

/etc/group isan ASCII filethat definesthegroups to which usersbelong. Thereis one entry per line, and each linehasthe 
format 

groupname ipasswd :GI D : li s e r _ I i st 

Thefield descriptionsare 

gr ou p_ na me T he name of the group. 

passwd The(encrypted) group password. If thisfield isempty, no password isneeded. 

gì d Thenumerical groupID. 

u s e r _ i i st Ali thegroup member'susernames, separated by commas. 

FILES 

/etc/group 

SEEALSO 

login(l), newgrp(l), passwd(5) 

Linux, 29 December 1992 



history 

history— Record of current and recently expired U senet arti ci es. 
D ESC RIFTIO N 

The fi le /news/nb/history keepsa record of ali articles currently stored in the news system, aswell asthosethat havebeen 
received but si nce expired. 

Thefileconsistsof text lines. Each linecorrespondsto one article The file is normally kept sorted in theorder in which 
articles are received, although thisisnot a requirement. innd(8) appendsa new li ne each timeit filesan article, and expire(8) 
buildsa new versi on of the file by removi ng old articles and purging old entries. 

Each line consists of two or three fi elds separated by atab, shown below as\t: 

<Me ssage-l D>\t date 
<Message- 1 D>\t date \t f II es 

T he Mes s a ge- 1 d field is the value of the article's M essage-ID header, includi ng the angle brackets. 

The date field consists of three subfields separated by a tilde. AH su bfi elds are the text representati on of thenumber of 
secondssincetheepoch— atime^t; seegettimeofday(2). Thefirst subfield isthe article's arrivai date. If copiesof the article 
are stili present, then thesecond subfield iseither the value of the article's Expires header ora hyphen if no expiration date 
wasspecified. If an article hasbeen expired, thesecond subfield will bea hyphen. Thethird subfield is the value of the 
article's D ate header, recordi ng when the article was posted. 
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T he f i i e s field isa set of entri es separateci by oneor morespaces. Each entry consistsof the nameof the newsgroup, a slash, 
and the article number. T hisfield isempty if the article has been expired. 

For example, an article cross-posteci to comp.sources.unix and comp.sources.d that wasposted on February 10, 1991, (and 
received threeminutes later) with an expiration dateof M ay 5, 1991, could havea history line (broken into two linesfor 
display) likethefollowing: 

<31 291itchi.foo.com> \t 666162000~673329600~666162180 
\t comp.sources.unix/1104 coup. sources .d/7056 

In additi on to thetextfile, thereisadbz(3z) database associ ated with the file that uses the M essage-l D field asa key to 
determi ne the offset in the text file where the associ ated linebegins. For historical reasons, the key includesthetrailing \0 
byte(which isnotstored in thetextfile). 

HISTORY 

W ritten by Rich $alz (rsaizuuunet.uu.net) for InterN etN ews. 
SEEALSO 

dbz(3z), expire(8), innd(8), news-recovery(8) 



hosts.nntp, hosts.nntp.nolimit 

hosts.nntp, hosts.nntp.nolimit— List of hosts that feed NNTP news. 
D ESC RIFTIO N 

The fi le /news/iib/hosts.nntp isread by innd(8) to get the list of hosts that feed the locai site Usenet news usi ng theN NTP 
protocol. The server readsthisfileat startup orwhen directed to by ctiinnd(8). When a hosts connectsto theN NTP port of 
thesystem on which innd isrunning, theserver will do acheckto seeif their Internet addressis the sameasoneof the hosts 
named in thisfile. If the host isnot mentioned, then innd will spawn an nnrpd(8) to process the connection, with the 
accepted connection on standard input and standard output. 

Commentsbegin with a number sign (#) and conti nuethrough the end of the line. Blank linesand commentsarealso 
ignored. Ali other lines should consist of two or three fi elds separateci by acolon. 

The first field should beeither an Internet addressin dotted-quad format or an addressthat can be parsed by 
gethostbyname(3). If a host's entry has multiple addresses, ali of them will beadded to the access list. The second field, which 
may be blank, is the password the fora gn host isrequired to use when first connecting. Thethird field, which may be 
omitted, isa list of newsgroupsto which the host may post arti cles. T his list isparsed asanewsfeeds(5) subscription list; 
groups not in the list are ignored. 

Becausemnd i s usuai I y started at system boottime, the locai nameserver may not befully operational when innd parsesthis 
file. Asawork-around, a ctiinnd reioad command can beperformed after adelay of an hour or so. It isalso possi bleto 
provide both a host's name and its dotted-quad addressin thefile. 

For example: 

## FOO has a password, UUNET doesn't. 
## UUNET cannot post to locai groups. 
## These are comment lines. 
news, f oo . com: magic 
uunet.uu.net: : !foo.* 

If thefilecontainspasswords, it should not beworld-readable. Thefile /news/iib/nosts.nntp.noiimit, if itexists, isread 
whenever the hosts.nntp fi le isread. It has the same format, although only the first field isused. Any host mentioned in this 
fileis not subject to the incoming connections li mit specified by innd's-c f lag. This can beused to allow locai hosts or time- 
sensitive peers to connect regardless of the locai conditions. 
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HI STORY 

W ritten by Rich $alz (rsaiz@uunet. uu.net) for InterN etN ews. 
SEEALSO 

ctlinnd(8), innd(8), nnrpd(8) 

hosts_access 

hosts access— Format of host access control files 
DESCRIVO N 

Thismanual page describesa simpleaccess control languagethat isbased on client (hostname/address, username) and server 
(process name) patterns. Examplesaregiven at the end. The impati ent reader can skip to the"Examples" section for aquick 
introduction. 

In the followi ng text, daemon isthe process name of a network daemon process, and client is the name or addressof a host 
requesting servi ce. N etwork daemon process namesarespecified in theinetd configuration file. 

ACCESS CONTROL FILES 

The access control software consultstwo files. The search stopsat the first match: 
Access wi II begranted when a (daemon, ci i ent ) pair matchesan entry in the /etc/hosts.aiiowfile. 
Otherwise, access will bedenied when a (daemon, ci i ent ) pair matchesan entry in the /etc/nosts.deny file 
Otherwise, access will begranted. 

A non-exi sting access control fileistreated as if itwerean empty file Thus, access control can beturned off by provi di ng no 
access control files. 

ACCESS CO NTROLRULES 

Each access control file consistsof zero or more li nesof text. Theselinesare processed in order of appearance. The search 
terni inates when a match isfound. 

A newlinecharacterisignored when itispreceded byabackslash character. 

Blank linesor linesthat begin with a # character areignored. 

Ali other linesshould satisfythefollowing format, thingsbetween n bang optional: 

daemonjlst : ci i enti i s t [ : s h e I I _ c omnia nd ] 

daemon. 1 1 st is a list of one or more daemon process names(argv[0] values) orwildcards. 

ci i ent.i i st isalistof oneormorehostnames, host addresses, patterns, orwildcardsthatwill bematched against the remote 
hostnameoraddress 

List elements should be separateci by blanks or commas. 

With theexception of N IS (YP) netgroup lookups, ali access control checks are case insensitive. 
PATTERNS 

The access control languageimplementsthefollowing patterns 

A stri ngthat begins with a . character: A client name or addressis matched if its last components match the specified 
pattern. Forexample, thepattern .tue.m matchesthehostnamewzv.win.tue.nl. 

A string that ends with a . character: A client name or addressis matched if its first fields match thegiven stri ng. For 
example, thepattern 131 .155. matches the addressof (almost) every host on the Eindhoven U ni versi ty network 
(131 .155. x .x). 
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A stri ng that beginswith a § character i s treated asa netgroup name N etgroups are usuai ly supportai on systemswith N IS 
(formerlyYP) databases. A eli ent hostnameismatched if itisa(host) member of the specified netgroup. 
An expression of theform n .n .n .n/m.m.m.m isinterpreted as a net /mas k pair. A di ent add ressi s match ed if net isequal to the 
bitwiseAND of theaddressand themask. For example, the net /mas k pattern 1 31 .155.72.0/255.255.254.0 matches every address 
in the range 131 .155.72.0 through 131 .155.73.255. 

WILDCARDS 

The access control language supports explicit wi Idcards: 

all If thistoken appearsin adaemon list, itmatchesall network daemon processnames. If theALL 

token appears in aclient list, it matches all client namesand addresses. 

local M atchesany stri ng that doesnot contain a dot character. Typical useisin client lists. 

unknown M atches any host whose name or address are unknown. Should be used with care H ostnames 

may beunavailabledueto temporary nameserver problems. A network address will be 
unavailablewhen the software cannot figure out what type of network it istalking to. 

known M atches any host whose name and address are known. Should be used with care: H ostnames 

may beunavailabledueto temporary nameserver problems. A network address will be 
unavailablewhen the software cannot figure out what type of network it istalking to. 

fail LiketheALL wildeard but causes the software to pretend that the scan of the current access 

control tabi e fai Is. fail isbeing phased out; itwill becomean undocumented feature. The 
except operator isa much cleaner alternative. 

OPERATO RS 

except Intended useisof theform: i i st_i except ì st j; thisconstruct matches anything that 

matches i isti unlessit matches i i st. 2. Thisconstruct can beused in daemon lists and in 
client lists. The except operator can benested: If the control language would permittheuse 
of parentheses, a except b except c would parse as (a except (b except c)). 

SHELLCOMMANDS 

If the fi rst-matched access control mie contai ns a shell command, thatcommand issubjected to thefollowing substitutions: 
%a Expandsto the remote host address. 

%c Expandsto client information: user ?host, user ?addr ess, a hostname, or just an address, 

dependingon how much information isavailable. 
%n Expandsto the remote hostname (or address, if the hostname is unavailable). 

%d Expandsto the daemon process name(argv[0] value). 

%p Expands to the daemon process ID. 

%u Expandsto the remote username (or unknown). 

%% Expandsto a single % character. 

Characters in % expansionsthat may confuse the shell arereplaced by underscores. Theresult isexecuted by a /bin/sh child 
process with standard input, output, and errar connected to /dev/nuii. Specify an &attheend of the command if you do not 
wantto waituntil it hascompleted. 

Shell commands should not rely on thePATH setti ng of theinetd. Instead, they should useabsolutepathnames, or they 
should begin with an explicit PATH=v»hat ever statement. 

REMOTE USERNAME LOOKUP 

When the client host supports the RFC 931 protocol or oneof itsdescendants(TAP, ident) thewrapper programscan 
retri ève additional information abouttheownerof a connection. When available, remote username information islogged 
togetherwith theclient hostname and can beused to match patterns like 

d a e mo n _ li s t : ... u s e r _ p a 1 1 e r n @h o s t _ p a 1 1 e r n ... 
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Thedaemon wrappers can be confi gured atcompiletimeto perform rule-dri ven usernamelookups (default) orto always 
interrogate the ci ient host. In thecaseof rule-driven usernamelookups, thepreceding rulewould cause usernamelookup 
only when both thedaemonj i st and the ho s t _ p a 1 1 e r n match. 

A user pattern hasthesamesyntaxasadaemon processname, hostname, or host address pattern, sothesamewildcardsand 
so on apply (but netgroup membership of usersisnot supported). Oneshould not get carri ed away with usernamelookups, 
however. 

The remote username informati on cannot betrusted when it isneeded most— that is, when the remote system hasbeen 
compromised. In general, all and (un)known are the only username patterns that makesense. 

U sername lookups are possi bleonly with TCP-based servicesand only when theclient host runsasuitabledaemon; in all 
othercasestheresult isunknown. 

A well-known UNIX kernel bug may cause lossof servi ce when username lookups are blocked by a firewall. Thewrapper 
readme document descri bes a procedure to find out if your kernel hasthis bug. 

Username lookups cause noticeabledelaysfor PC users. The default ti me-outfor username lookups isten seconds: too short 
to copewith slow networks but long enough to irritate PC users. 

Selective username lookups can alleviatele last problem. For example, a rulelike 

daemonjist : @pc net gr oup ALL@ALL 

would match membersof thepcnet group withoutdoing username lookups but would perform username lookups with all 
other systems. 

EXAMPLES 

T he language is flexi ble enough that differenttypesof access control policycan beexpressed with aminimum of fuss. 
Although the language usestwo access control tables, the most common poli cies can beimplemented with oneof thetables 
bei ng tri vi al oreven empty. 

When reading thefollowing examples, it isimportant to real ize that the allow tableisscanned beforethedeny table, that the 
search termi nates when a match isfound, and that access isgranted when no match isfound at all. 

The examples use host and domain names. They can beimproved by includi ng address or network/netmask informati on to 
reduce the impact of temporary nameserver lookup failures. 

MOSTLYCLOSED 

In thiscase, access isdeni ed by default. Only explicitly authorized hosts are perni itted access. 
Thedefault policy (no access) isimplemented with atrivial deny file: 
/etc/hosts.deny: 
ALL: ALL 

This denies ali serviceto all hosts, unless they are perm itted access by entries in the allow file. 
The explicitly authorized hosts are I i sted in theaiiow file: 

/etc/hosts . allow: 

ALL: LOCAL @s o me_ net g r ou p 

ALL: .foobar.edu EXCEPT terminalserver.foobar.edu 

The first mie perm its access to all servi cesfrom hosts in the locai domain (no . in the hostname) and from membersof the 
some, net group netgroup. Thesecond rule perm its access to all servicesfrom all hosts in the .foobar.edu domain, with the 

exception Ofterminalserver.foobar.edu. 



MOSTLYOPEN 

Here, access isgranted by default; only explicitly specifi ed hosts are refused servi ce. 
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The default policy (access granted) makestheallow file redundant so that it can beomitted. Theexplicitly non-authorized 
hostsarelisted in thedeny file: 

/etc/hosts.deny: 

ALL: some.host.name, .some. domain 

ALL EXCEPT in.fingerd: other.host.name, .other. domain 

Thefirst mie denies some hosts ali services; thesecond mie stili permits finger requestsfrom other hosts. 
BOOBYTRAPS 

Thenextexample permits tftp requestsfrom hosts in the locai domain. Requestsfrom anyother hosts are denied. Instead of 
therequested file afinger probeissentto theoffending host. The result ismailed to thesuperuser. 

/etc/hosts.allow: 

in.tftpd: LOCAL, .my. domain 
/etc/hosts.deny: 

in.tftpd: ALL: ( /some/where/saf e_f inger -1 @%h ] \ 
/usr/ucb/mail -s %d-%h root) & 

The safe_f inger command comes with thetcpd wrapper and should be instai led in a sui tabi e place. It limits possi bledamage 
from datasent by the remote finger server. It gives better protection than the standard finger command. 

Theexpansion of the%h (remote host) and %d (servicename) sequencesisdescribed in thesection on shell commands. 

Warning: Do not booby-trap your finger daemon, unlessyou areprepared for infini te finger loops. 

On network firewall systems, thistrick can becarried even further. Thetypical network firewall only providesalimited set of 
servi cesto theouterworld. Ali other services can be"bugged" just li ke the precedi ng tftp example. The result isan excellent 
early-warning system. 

DIAGNOSTICS 

An errar isreported when asyntaxerror isfound in a host access control mie, when thelength of an access control mie 
exceedsthecapacity of an internai buffer, when an access control rule is not terminateci by a newlinecharacter, when the 
result of %<cha racter > expansion would overflow an internai buffer, and when a system cali fai Is that shouldn't. Ali problems 
are reported via the sysiog daemon. 

FILES 

/etc/hosts.aiiow, (daemon ,c i ent ) pai rs that are granted access, 
/etc/hosts.deny, (daemon.ci i ent ) pai rs that are denied access 

SEEALSO 

tcpd(8), TCP/IP daemon wrapper program 
BUGS 

If a nameserver lookup timesout, thehostnamewill not beavailableto the access control software, even though the host is 
registered. 

Domain nameserver lookups are case insensitive; N IS (formerly YP) netgroup lookups are case sensitive. 
AUTHOR 



Wietse Venema (wietse@wzv.win. tue. m), Department of M athematicsand Computing Science, Eindhoven U ni versi ty of 
Technology, Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The N etherlands. 
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hosts_options— H ost access control languageextensions. 
D ESC RIPTIO N 

Thisdocument describes optional extensionsto thelanguagedescribed in thehosts_access(5) document. Theextensionsare 
enabled at program buildtimeby editing the makefile. 

The exten sible language uses thefollowing format: 

daemonjist : ci i e n t _ I i s t : opti or : option ... 

Thefirst two fieldsare described in thehosts_access(5) manual page. The remainder of the rulesis a list of zero or more 
options. Any : characterswithin optionsshould beprotected with a backslash. 

An option isof theform keyword or keyword = «al ne. 0 ptionsare processed in thespecified order. W ith some options, the 
vai ue i s su bj ected to %<c h a r a c t e r > su bsti tuti ons. 



OPTIONS 

severity = mail. info 



allow (deny) 



C hange the severi ty level atwhich theeventwill belogged. Facility names(such as 
mail) are optional and arenot supported on systemswith older sysiog implementa- 
tions. The severity option can beused to emphasizeorto completely ignorespecific 
events. 

Grant(deny) service, even when thematched rulewasfound in the hosts. deny 
(hosts. allow) file. These options must appearattheend of arule. 

With the aiiow and deny keywords, it is possi bleto keep ali access control ruleswithin a single fi le— for example, in the 

hosts . allow fi le: 

ALL: .friendly. domain: allow 
ALL: ALL: deny 

This permits access from specific hosts only. On theother hand, 

ALL: .trouble.makers: deny 
ALL: ALL: allow 

This permits access from ali hosts except a few troublemakers. 

twist = sneii_command Replace the current process by an instance of the 

specified shell command, after performingthe 
%<c h a r a c t e r > expansions described in the 
hosts_access(5) manual page, stdin, stdout, and 
stdem are connected to the remote client process. 
Thisoption must appear attheend of a rule. 
Examples: 

Some bounce message sends a customized bounce 
messageto theremote client instead of runningthe 
real FTP daemon. 

Runs /some/other/in.telnetd without polluting itS 

command-line array or its process environment. 
Warning: In caseof U D P services, do not twist into 
commandsthat use the standard I/O orthe 
read(2)/write(2) routinesto communicate with the 
client process; UDP requiresotherl/O primitives. 
Execute the shell command in achild process, after 
performingthe%<character> expansions described 
in thehosts_access(5) manual page. The command 



in.ftpd : ... : twist = /bin/echo 421 



in.telnetd : ... : twist = PATH=/some/other; exec in.telnetd 



spawn = shell_command 
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spawn = (/some/where/safe_finger -1 @%h | /usr/ucb/maìl root) & 



umask = 022 



keepalive 



linger = number_of_seconds 

nice = niceval 
nice (no argument) 

user = nobody 



group = tty 



setenv = name vai ne 



isexecutoi with stdin, stdout, and stderr 

connected to the nuli device so that itwon't mess 
up the conversati on with the remote host. Example: 
Executes, in a background child process, theshell 

COmmand safe_finger -1 @%h j mail root after 

replaci ng %n by the name or address of the remote 
host. 

Theexampleusesthesafe_finger command 
instead of the regular finger command to limit 
possi bledamagefrom data sent by thefinger server. 
Thesafe_finger command i s part of thedaemon 
wrapper package it isawrapper around the regular 
fi nger command that fi Iters the data sent by the 
remote host. 

Liketheumask command that is built into theshell. 
An umask ofo22 prevents the creation of files with 
group and world write permission. The umask 
argument should bean octal number. 
C auses the server to periodically send amessageto 
the client. The connection isconsidered broken 
when the client doesnot respond. The keepalive 
option can beuseful when usersturn off thdr 
machinewhile it is stili connected to a server. The 
keepalive option is not useful for datagram (U D P) 
services. 

Specifi eshow long the kernel will try to delivernot- 
yet delivered data after the server process closes a 
connection. 

C hange the nice value of the process (default 10). 
Specify a positive valueto spend more CPU 
resources on other processes. 
Assumerne privilegesof thenobody account. Thisis 
useful with metd implementations that run ali 
servi ceswith root privilege. It isgood practiceto 
run services such astinger at a reduced privilege 
level. 

Assume the privilegesof the tty group. T hi s is 
useful mostly in combination with theuser option. 
In orderto switch both user and group IDs, switch 
group ID beforeswitching user ID . 
Place a (name, vai ne) pai r i nto the process environ- 
ment. The vai ue issubjected to %<c h a r a c t e r > 
expansionsand may contain whitespace(but 
leading and trai li ng blanks are stri pped off). 
Warning: Many network daemons reset their 
environment beforespawning a login or shell 
process. 



inittab 



rf c931 = t i meout _ i n_ s e c ond s 

rfc93i (no argument) Look up the remote user name with the RFC 931 

(ident and so on) protocol. Thisoption issilently 
ignored in case of servi ces based on transports other 
than TCP. It requiresthat the client system runsan 
RFC 931 (ident and so on) compliant daemon and 
may cause noticeabledelays with connectionsfrom 
non-U N IX hosts. Thetime-out period isoptional. 
If no time-out is specified, a default value is taken. 

DIAGNOSTICS 

When a syntax errar isfound in an access control rule, the errar isreported to thesysiog daemon; further options will be 
ignored, and service is denied. 

SEEALSO 

nosts_access(5), the default access control language 
AUTHOR 

WietseVenema (wietseewzv.win.tue.nl), Department of M athematicsand Computing Science, Eindhoven U ni versi ty of 
Technology, Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The N etherlands. 
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inittab— Format of the inittab fileused by theSysV-compatibleinit process. 
DESCRIVO N 

The inittab filedescribeswhich processes are started at bootup and during normal operation (such as/etc/rc, gettys). init 
disti nguishes multiple run levels, of which each can haveitsown set of processes that are started. Valid run e v e i s are 0-6 and 
a, b, and cfor ondemand entri es. An entry in the inittab fi le has the following format: 

d : r u n I e v e I s : a c t i o n : p r o c e s s 

Lines beginning with # are ignored. 

d A uniquetwo-character-sequence which identifiesan entry in inittab. 

N ote: For gettys or other login processes, the i d fi dd should bethetty suffixof the 
corresponding tty, such asi for ttyi. Otherwise, the login accounting will not work 
correctly. Thisisa bug in login and will befixed. 

runi evei s Describesin which run levels the speci fi ed action should be taken. 

acti on Describes which action should be taken. 

process Specifiesthe process to beexecuted. If the process field starts with a+ character, init will 

not do utmp and wtmp accounting for that process. Thisisneeded for gettys that insiston 
doing their own utmp/wtmp housekeeping. Thisisalso a historic bug. 



Valid actionsare 

respawn 
wait 



once 
boot 



The process will berestarted whenever it terminates (such asgetty). 

The process will be started oncewhen the specified run leve! isentered and init will wait 

for itstermination. 

The process will beexecuted oncewhen the specified run leve! isentered. 
The process will beexecuted during system boot. The run level field is ignored. 
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T he process will beexecuted during system bootwhileinit waitsfor its terni ination (such 
as/etc/rc). Theruni evei field isignored. 
Thisdoesnothing. 

A process marked with ondemand will beexecuted whenever the specified ondemand run leve! 
iscalled. However, norunievei changewill occur. 

An initdefauit-entry specifiestherun level thatshould beentered after system boot. If 
noneexists, init will ask forar uni ev e on the console. 

The process will beexecuted during system boot. Itwill beexecuted before any boot or 
bootwait entri es. 

The process will beexecuted when init receivesthesiGPvm signal, indicatingthatthereis 
somethingwrongwith the power, init will waitfor the process to finish before conti nuing. 
Aspowerwait but init will not wait for the processes completion. 
The process will beexecuted when init receivesthesiGPWP. signal, provided there is a fi le 
called /etc/powerstatus contai ni ng the word ok. Thismeansthatthepower has come back 
again. 

The process will beexecuted when init receivesthesiGiNT signal. Thismeansthat someone 
on the system console pressed the C trl-hAlt-HD e! key combinati on. Typically, onewantsto 
executesomesort of shutdown either to get into single- user level orto reboot the machine. 

The r uni e «e field may contai n multiplecharactersfor different run levels, such asi23 if the process should bestarted in run 
levelsl, 2 and 3. ondemand entries may contai n an a, b, ore. Theruni evei field of sysinit, boot, and bootwait entri es are 
ignored. 

When the run level ischanged, any running processes that are not specifi ed forthenew run level are ki lied, first with sigterm 
and then with sigkill. 

EXAMPLES 

Thisisan exampleof an inittabthat resemblestheold Linux inittab: 

# inittab for linux 
id : 1 : initdef ault : 
re: : bootwait: /etc/rc 

1 : 1 : respawn : /etc/getty 9600 ttyl 
2:1 : respawn: /etc/getty 9600 tty2 
3:1 :respawn:/etc/getty 9600 tty3 
4:1 :respawn:/etc/getty 9600 tty4 

Thisinittab fileexecutes /etc/rc during boot and startsgettys on ttyi-tty4. 
A more elaborate inittab with different run levels(seethecommentsinside) is 

#Level to run in 
id:4:initdefault: 
ud: :boot: /etc/update 
re: :bootwait: /etc/rc 
cr: :boot: /etc/crond 
# 

# level 1 : getty on ttyl 

# level 2: getty on ttyl -4 

# level 3: tty1-4, dialin via modem(ttys2) 

# level 4: ttyl -4, ttyb 
# 

mr: 126: once: /usr/bin/nodialin 
mi: 345 : once : /usr/bin /dialin 
1 :1234:respawn: /etc/getty 9600 ttyl 
2:234: respawn : /etc/getty 9600 tty2 
3:234: respawn : /etc/getty 9600 tty3 



bootwait 
off 

ondemand 

initdefault 

sysinit 

powerwait 

powerfail 
powerokwait 

ctrlaltdel 



i nn.conf 




4:234: respawn : /etc/getty 9600 tty4 
s2:3:respawn: /etc/mgetty ttys2 19200 
b:4: respawn: /etc/getty 19200L ttyb 
ca: :otrlaltdel: /etc/shutdown -t3 -rf now 

FILES 

/etc/inittab 

AUTHOR 

init waswritten by M iquel van Smoorenburg (miqueisedrinkei.ni.mugnet.org). Themanual pagewaswritten by Sebasti an 

Ledere" (ledererWrancium.informatik.uni-bonn.de) and modified by M ichael H aardt (u31b3hs@pool.informatik.rwth- 
aachen.de). 

SEEALSO 

init(8), telinit(8) 

13 Mayl993 



inn.conf 

inn . conf — C onfigurati on data for I nterN etN ews program s. 
D ESC RIFTIO N 

Thefile /news/iib/inn.conf isused to determine various parameters. Blank linesand lines starti ngwith a number sign (#) are 
ignored. Ali other lines specify parameters that may beread and should beof thefollowing form: 

name : [optional whitespace] value 

Everything after the whitespace and up to the end of the line istaken as the «ai ne; multi-word values should not be put in 
quotes. T he caseof names is significanti server is not the same as server or server. 

Some parameters specified in thefile may beoverridden by environment variables, and some fi le parameters may beused to 
mask real data, such aswhen hidingacluster of hostsbehind a single electronic mail hostname. Thecurrent set of parameters 
isasfollows: 

fromhost T his is the name of the host to usewhen buildingtheFrom header line. The default isthe 

fui ly qualified domain name of the locai host. The value of the fromhost environment 

variable, if itexists, overridesthis. 
moderatormaiier T his names the default machine that containsforwardingaliasesfor ali moderated groups. It 

isonly used if themoderators(5) file doesn't exist or if thegroup isnot matched by that file. 

Thevalueisinterpreted as a pattern match; seemoderators(5). 
organization This specifies what to put in the Organization header if it i s blank. The value of the 

organization envi ronment variable, if it exists, overridesthis. 
pathhost This specifies howto namethe locai sitewhen buildingthePath header line The default is 

thefully qualified domain name of the locai host. 
server T his specifies the name of the N N T P server to which an article should beposted. The value 

of the nntpserver environment variable, ifit exists, overridesthis. 
domain Thisshould be the domain nameof the locai host. It should not havea leading period, and 

it should not bea full host address. It isused only if the GetFQDN routine in iibinn(3) cannot 

get thefully qualified domain name by usi ng either thegetnostname(2) orgethostbyname(3) 

cai la The check isvery simple; if either routine return sa namewith a period in it, then it is 

assumed to havethefull domain name. 



1142 



Part V: FileFormats 



Three parameters areused only by nnrpd when accepting posti ngsfrom clients: 

mime-version If this parameter is present, then nnrpd will add thenecessary M IM E (M ulti purpose Internet 

M ail Extensions) headersto ali any articlesthat do not havea M ime-Version header. This 
parameter specifiestheM IM E versi on and should normally bei .0. 

mime-contenttype If M IM E headers are bei ng added, this parameter speci fi es the vai ueof theContent-Type 

header. The default value istext/piain; charset=us-Ascn. 

mime -encoding If M IM E headers are bei ng added, this parameter specifi es the value of the Content- 

Transfer-Encoding header. The default valueiS7Pit. 

Notethat this file can beidentical on ali machinesin an organization. 
EXAMPLE 

fromhost: foo.com 
moderatormailer: %s@uunet . uu . net 

organization: Foo, Incorporated 

#pathhost: U Se FQDN . 

server: news.foo.com 
domain: foo.com 

T his fi le is i ntended to be fai ri y stati c; any changesmadeto it are typically not reflected until a program restarts. 
HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

libinn(3), moderators(5) 



innwatch.ctl 

innwatch.ctl— Control U Senet Supervision byinnwatch. 

D ESC RIPTIO N 

The fi le /news/iib/innwatch.cti isused to determi ne what actionsaretaken during the peri odic supervisions byinnwatch. 

Thefileconsistsof aseriesof lines; blank linesand linesbeginningwith a number sign (#) areignored. Ali other linesconsist 
of seven fields, each preceded by adelimitingcharacter: 

: label : state : condition : test : limit : command : reason 

Thedelimiter can beany oneof several non-alphanumeric charactersthat doesnot appear elsewherein the line; thereisno 
way to quote itto include it in any of the fields. Any of !, ,, ■„ or ? isagood choice. Each li ne can havea di fferent 
del imi ter; the first character on each line is the del imi ter for that line Whitespacesurroundingdelimiters, except beforethe 
first, isignored and doesnotform part of thefields; whitespacewithin fields ispermitted. Ali delimiters must be present. 

The first field is a label for the control line. It isused asan internai state indicator and in ctiinnd messagesto control the 
server. If omitted, the line number isused. 

Thesecond field specifieswhen thiscontrol lineshould beused. It consistsof a list of labelsand special indicatorsseparated 
by whitespace. If thecurrent state matchesagainst any of the labels in this field, this li ne will beused asdescribed below. The 
values that may be used are 

This line matches if the current state is the same as the label on this li ne or if the current state 
isrun, theinitial state. T his is also the default state if this field isempty. 



innwatch.ctl 



+ T his li ne matches if the current state is run. 

This linealways matches. 
label This line matches if the current state is the specified i a b e i . 

-label T his li ne matches if the current state isnot the specified i abei . 



Thethird field specifies a shell command that isinvoked if this line matches. Do not useany shell filenameexpansion 
characters such as*, ?, or [ (even quoted, they're not likely to work asintended). If the command succeeds, asindicated by 
itsexit status, it isexpected to haveprinted a single integer to standard output. T his gives the valueof this control line, to be 
used below. If the command fails, the li ne isignored. The command isexecuted with its current directory setto the 
newsspool directory, /news/spooi. 

Thefourth field specifies the operatorto useto test the value returned above. It should beone of thetwo-letter numeric test 
operatorsdefined in test(l) such aseq, it, and thelike. Theleadingdash (-) should not beincluded. 

Thefifth field specifies a Constant with which to compare the value usi ng the operator just defi ned. This isdoneby invoking 
the command 

test value -operator Constant 

The line issaid to "succeed" if it returnstrue. 

Thesixth field specifies what should bedoneif the li ne succeeds and in somecasesif itfails. Any of thefollowingwordsmay 
beused: 

tnrottie Causesinnwatcn to throttle the server if this line succeeds. It also sets the state to the valueof 

the line's label. If the li ne fails and the state was previ ously equal to the label on this line (that 
is, thislinehad previ ously succeeded), then ago command will besent to the server, and 
innwatch will return to the run state. The throttie isonly performed if the current state is run 
orastateotherthan thelabel of thisline, regardlessof whether the command succeeds. 

pause Isidentical to throttie except that the server ispaused. 

shutdown Sends a shutdown command to the server. Itisforemergency useonly. 

tiush Sends a f ìusn command to the server. 

go Causes innwatch to send ago command to the server and to set the state to run. 

exit C auses innwatch to exit. 

skip The result of the control file is skipped for the current pass. 

The last field specifies the reason that isused in thosectiinnd commandsthat requireone M ore strictly, it ispart of the 
reason; innwatch appendssomeinformation to it. In orderto enable other sites to recognize thestate of the locai innd server, 
thisfield should usually be setto oneof several standard values. U se no space if theserver is rejecti ng articles becauseof a 
lack of filesystem resources. Useioadav if theserver is rejecti ng articles because of a lack of C PU resources. 

Once innwatch hastaken some action as a consequence of its control line, it ski ps the rest of the control filefor this pass. If 
the action wasto restart theserver (that is, issueago command), then thenext pass will commencealmost immediately so 
that innwatch can discover any other conditi on that may mean that theserver should besuspended again. 

EXAMPLES 

@@@df .|awk ' NR==2 {print $4} 1 @lt@10000@throttle@No space 

&9@df -i . |awk ' NR==2 {print $4} 1 @lt@1000@throttle@No space (inodes) 

The first I ine causes the server to bethrottled if the free space drops below 10000 units (usi ng whatever unitsdt uses) and 
restarted again when free space in creases above thethreshold. 

Thesecond li ne does the same for inodes. 

Thenextthreelinesactasa group and should appear in thefollowingorder. It iseasier to explain them, however, if they are 
described from the last up. 
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! load ! load hiload ! loadavg ! lt ! 5 ! go ! 

: hiload : + load : loadavg : gt : 8 : throttle : loadav 

/ load /+/ loadavg /ge/6/pau se /loadav 

The final line causes the server to bepaused if innwatch isin therun state and the load average ri sesto, or above, six. The 
state is set to ioad when thishappens. The previous line causes the server to bethrottled when innwatch isin thenun or load 
state, and the load average ri ses above eight. The state is setto hiioad when thishappens. N otethat innwatch can switch the 
server from paused to throttied if the load average ri ses fra m below sixto between six and seven and then to above eight. The 
first li ne causes the server to besent a go command if innwatch isin the ioad or hiioad state and the load average drops below 
fi ve. 

N otethat ali three lines assume a mythical command loadavg that isassumed to printthecurrent load average asan integer. 
In morepractical circumstances, a pi pe of uptime into awk is more likely to beuseful. 

BUGS 

T hisfi le must betailored foreach individuai site; thesamplesupplied istruly no morethan asample. Thefileshould be 
ordered so that the more common problemsaretested first. 

Therun state isnot actually identified by the label with that three letter name, and usi ng it wi II notwork asexpected. 

Using an "unusual" character for the deli miter such as (,*,&, ■", and thelikeis likely to lead to obscureand hard-to-locate 
bugs. 

HI STORY 

Written by (kre@munnari.oz.au) for InterN etN ews. 
SEEALSO 

innd(8), ctlinnd(8), news.daily(8) 

ipc 

ipc— System V interprocesscommunication mechanisms. 
SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

# include <sys/sem.h> 

# include <sys/shm.h> 

D ESC RIPTIO N 

Themanual pagerefersto the Linux implementation oftheSystem V interprocesscommunication mechanisms: message 
queues, semaphoresets, and shared memory segments. In thefollowing, theword resource meansan instanti ation of one 
among such mechanisms. 

RESOURCE ACCESS PERMISSIONS 

Foreach resource, thesystem usesacommon structureof typestruct ipc_perm to storeinformation needed in determining 
permissionsto perform an ipc operati on. Theipc_perm structure defined by the<sys/ipc.h> system header file, includesthe 
following members: 

ushort cuid; /* creator user id */ 

ushort cgid; /* creator group id */ 

ushort uid; /* owner user id */ 

ushort gid; /* owner group id */ 

ushort mode; /* r/w permissions */ 



ipc 



The mode member of theipc_perm structure defines, with its lower ninebits, the access perni issionsto theresourcefor a 
processexecuting an ipc system cali. The permissions are interpreted asfollows: 

8400 Read by user. 

0200 W ri te by user. 

0040 Readbygroup. 
0020 Writeby group. 

0004 Read by others. 

0002 W ri te by others. 

BitsOlOO, 0010, and 0001 (theexecute bits) areunused by the system. Furthermore"write" effectively means "alter" for a 
semaphoreset. 

T h e sam e system h eader f i I e def i n es al so th e f o 1 1 ovvi ng sym bo I i c co n stan ts: 
ipc_creat C reate entry if key doesn't exists. 

ipc excl Fail if key exists. 

ipc_nowait Errar ifrequest must wait. 

ipc_private Private key. 

ipc_rmid Remove resource. 

ipc set Set resource options. 

ipc_stat G et resource options. 

N otethat ipc_private isa key_t type, whereasall the others sym boli c constants are flag fields O Rable into an int type 
variable 

MESSAGEQUEUES 

A messagequeue isuniquely identified by a positive integer (itsnsqid) and hasan associated data structure of type struct 
msquid_ds, defined in <sys/msg.h>, containing thefollowing members: 

struct ipc_perm msgjerm; 

ushort msg_qnum; /* no of messages on queue */ 

ushort msg_qbytes; /* bytes max on a queue */ 

ushort msg_lspid; /* pid of last msgsnd cali */ 

ushort msg_lrpid; /* pid of last msgrcv cali */ 

time_t msg_stime; /* last msgsnd time */ 

time_t msg_rtime; /* last msgrcv time */ 

time_t msg_ctime; /* last change time */ 



msg_perm 

msgjnum 

msg_qbytes 

msgjspid 

msg_lrpid 

msg_stime 

msg_rtime 

msg_ctime 



ipc_perm structure that specifies the access permissions on the messagequeue. 

N umber of messages currently on the message queue. 

M aximum number of bytes of message text allowed on the message queue. 

ID of the process that performed the last msgsnd system cali. 

ID of the process that performed the last msgrcv system cali. 

Time of the last msgsnd system cali. 

T ime of the last msgcv system cali. 

Timeof the last system cali that changed a member of themsqid_ds structure. 



SEMAPHORE SETS 

A semaphoreset isuniquely identified by a positive integer (itssemid) and hasan associated data structure of type struct 
semid_ds, defined in <sys/sem.h>, contai ni ng the followi ng members: 



struct ipc_perm sem_perm; 

time_t sem_otime; /* last operation time 



/ 
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time_t sem_ctime; /* last change time */ 
ushort semnsems; /* count of sems in set */ 



sem_nsems 



sem_perm 



sem_ctime 



sem_otime 



ipc_pe™ structure that speci fi es the access permissionson thesemaphoreset. 
Timeof last semop system cali. 

T ime of last semcti system cali that changed a member of the above structure or of one 
semaphore belongi ng to the set. 

N umber of semaphoresin the set. Each semaphore of the set isreferenced by a non-negative 
integer ranging from 0 to sem_nsems-i . 



A semaphore is a data structure oftypestruct seni containingthefollowing members: 

ushort semval; /* semaphore value */ 

short sempid; /* pid for last operation */ 

ushort semncnt; /* no. of awaiting semval to increase */ 

ushort semzcnt; /* no. of awaiting semval = 0 */ 

semvai Semaphore value a non-negative integer. 

sempid ID of thelast processthat performed a semaphore operation on this semaphore. 

semncnt N umber of processes suspended awaiting for semvai to increase. 

semznt N umber of processes suspended awaiting for semvai to becomezero. 

SHARED MEMORY SEGMENTS 

A shared memory segment isuniquely identified by a positive integer (itsshmid) and hasan associated data structure oftype 
struct shmid_ds, defined in <sys/shm.h>, containing thefollowing members: 

struct ipc_perm shm_perm; 
int shm_segsz; /* size of segment */ 
ushort shm_cpid; /* pid of creator */ 
ushort shm_lpid; /* pid, last operation */ 
short shmjiattch; /* no. of current attaches */ 
time_t shm_atime; /* time of last attach */ 
time_t shm_dtime; /* time of last detach */ 
time_t shm_ctime; /* time of last change */ 



shmjerm 


ipc_perm structure that speci fi es the access permissionson the shared memory segment. 


shm_segsz 


Size in bytes of the shared memory segment. 


shm_cpid 


1 D of the process that created the shared memory segment. 


shm_lpid 


ID of thelast processthat executed a shmat orshmdt system cali. 


shm_nattch 


N umber of current alive attaches for this shared memory segment. 


shm_atime 


Timeof thelast shmat system cali. 


shm_dtime 


Timeof thelast shmdt system cali. 


shm_ctime 


Timeof thelast shmcti system cali that changed shmid_ds. 



SEEALSO 

ftok(3), msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2), semop(2), shmat(2), shmctl(2), shmget(2), shmdt (2) 

Linux 0.99.13, 1 N ovember 1993 



issue 

issue— I ssue i denti fi cati on fi le. 
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DESCRIVO N 

Thefile /etc/issue isatextfilethatcontainsamessageorsystem ideiti fi cation to be printed before the login prompt. It 
may contain variousechar and \c har sequencesif supported bygetty(l). 

FILES 

/etc/issue 

SEEALSO 

getty(l), motd(5) 

Linux, 24 J uly 1993 

lilo.conf 

ìiio.conf — Configuration filefor LI LO. 
DESCRIVO N 

Thisfile, by default /etc/mo.conf, isread by the boot loader instai ler LI LO (seemo(8)). 

It might look asfollows: 

boot = /dev/hda 

delay = 40 

compact 

vga = normal 

root = /dev/hda1 

read-only 

image = /zlmage-1 .5.99 

label = try 
image = /zlmage-1 .0.9 

label = 1.0.9 
image = /tamu/vmlinuz 

label = tamu 

root = /dev/tidb2 

vga = ask 
other = /dev/hda3 

label = dos 

table = /dev/hda 

This configuration file specifies that LI LO usestheM aster Boot Record on /dev/hda. (For a discussi on of thevariouswaysto 
use LI LO and the interaction with other operati ngsystems, seeuser.tex from the LI LO documentation.) 

When booti ng, the boot loader wi II wait 4 seconds (40 deciseconds) foryou to press Shift. If you don't, then the first kernel 
image mentioned (/zimage-1.5.99, which you probably instai led just 5 minutesago) wi 1 1 bebooted. If you do, the boot 
loader wi II ask you which i magete boot. In case you forgot the possi blechoices, press T ab (or ? if you havea U .S. keyboard), 
and you will bepresented with a menu. You now havethechoiceof booti ng this brand new kernel, an old trusted kernel, or 
a kernel on another root fi le system (just in case you did something stupì d on your usuai root) or booting a different 
operating system. Th ere can beup to 16 images mentioned in mo.conf. 

Ascan beseen previously, a configuration fi le starts with a number of global options (thetop six lines in theexample), 
followed by descriptionsof the options for the various images. An option in an image description will override a global 
option. 
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GLOBALOPTIONS 

Therearemany possible keywords. The description thatfollows isalmost literally from user.tex (just slightly abbreviateci) 

backup=b a c k u p - file 



boot=b o o t ■ devi ce 



compact 



default=name 



delay=t s ec s 



disk=d e v ce - name 



disktab=d i sktab-fi I e 



fix-table 



force-backup=backup- 
ignore-table 
install=boot ■ sector 

linear 



lock 

map=ma p- file 
message=message- 



Copy theoriginal boot sector to backup-fi i e (which mayalso beadevice, such as/dev/nuii) 

instead Of /boot/boot.NNNN. 

Sets the name of the device (such asa hard disk partition) that contains the boot sector. If 
this keyword isomitted, the boot sector isread from (and possi blywritten to) the device 
that is currently mounted as root. 

Triesto merge read requestsfor adj acent sectors into a single read request. Thisdrastically 
reducesload timeand keepsthemap smaller. Using compact i s especi al ly recommended 
when booting from a floppy disk. 

Uses the speci fi ed imageas the default boot image. If defauit isomitted, theimage 
appearing first in theconfiguration fileisused. 

Specifies the number of tenths of a second the boot loader should wait before booting the 
first image. This isuseful on systems that immedi atei y boot from the hard disk after 
enabli ng the keyboard. The boot loader doesn't wait if deiay isomitted or is set to zero. 
Defines non-standard parametersforthespecified disk. See serti on "D isk Geometry" of 
user.tex for details. 

Specifi es the name of the disk parameter table. Themap instai ler looksfor /etc/disktab if 
disktab isomitted. Theuse of disktabs isdiscouraged. 

Thisallows LI LO to adjust 3-D addressesin partition tables. Each partition entry contains a 
3-D (sector/head/cylinder) and a linear addressof the first and thelast sector of the 
partition. If a partition isnottrack-aligned and if certain other operating systems (such as 
PC/M S-DOS or OS/2) are using the same disk, they may changethe3-D address. LI LO 
can suore its boot sector only on partitionswhereboth address typescorrespond. LILO 
readjusts incorrerti 3-D start addressesif fix-tabie isset. 

W arni ng: This does not guaranteethat other operating systems may not attempt to reset the 
address later. It isalso possiblethatthischangehas other, unexpected sideeffects. The 
correct fix isto repartition the drive with a program that does ali gn partitionsto tracks. 
Also, with some disks (such assomelargeEIDE diskswith address translati on enabled), 
under somecircumstances, it may even beunavoidableto haveconflicting partition table 
entri es. 

Like backup but overwritean old backup copy if it exists. 
Tells LILO to ignorecorrupt partition tables. 

Instali thespecified fileasthenew bootsector. If instali isomitted, /boot/boot.b isused as 
the default. 

Generate linear sector ad dresses instead of sector/head/cylinder addresses. Linear addresses 
aretranslated at runtimeand do not depend on disk geometry. N otethat boot disks may 
not be portableif linear isused because the BIOS servi ceto determi ne the disk geometry 
does not work reliably for floppy disks. When using linear with large disks, /sbin/mo may 
generate references to i naccessible disk areas because 3-D sector addresses are not known 
before boot ti me. 

E nables automati c recordi ng of boot command li nes as the defaults for the followi ng boots. 

Thisway, LILO "locks" on achoiceuntil itismanuallyoverridden. 

Specifies the location of themap file If map isomitted, the fi le /boot/map isused. 

Specifi es a fi le contai ni ng a message that isdisplayed before the boot prompt. N o messageis 

displayed whilewaitingfor ashifting key after printing lilo . In the message, theFF 

character (Ctrl+L) clears the locai screen. T he size of the message file is li mited to 65,535 

bytes. Themap filehasto berebuiltif the message file ischanged ormoved. 

D isableswarningsabout possible future dangers. 
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optional 

password=password 
prompt 

restricted 
serial=p a r a me t e r s 



Theper-imageoption optional appliesto ali images. 
Theper-imageoption password=... appliesto ali images. 
Forces entering the boot prompt without expecting any prior key presses. U nattended 
reboots are im possi bl e if prompt is set and timeout isn't. 
Theper-imageoption restricted appliesto ali images. 

E nables control from aserial line. The specified serial port isinitialized and thebootloader 
is accepting input from it and from the PC 's key board. Sending a break on the serial line 
correspondsto pressing a Shift key on the console in order to get the boot loader's 
attenti on. Ali boot images should be password-protected if the serial access is lesssecure 
than access to theconsole, such asif the line isconnected to a modem. The parameter string 
hasthefollowing syntax: 

<p o r t >[ ,<bps >[<par i t y >[<bi t s >] ] ] 

<port >: Thenumber of the serial port, zero-based. 0 correspondsto COMI alias/dev/ttyse, 
and so on. Ali four portscan beused (if present). <bps >: Thebaud rate of the seri al port. 
Thefollowing baud ratesaresupported: 110, 150, 300, 600, 1200, 2400, 4800, and 9600 
bps. Default is2400 bps. 

<pari t y >: T he parity used on the serial line. The boot loader ignores input pari ty and stri ps 
theeighth bit. Thefollowing (uppercase or lowercase) characters are used to descri bethe 
parity: n for no parity, e for even parity, and 0 for odd parity. 
<bi ts>: Thenumber of bitsin acharacter. Only 7 and 8 bits are supported. Default is 8 if 
parity is none and 7 if parity is even or odd. 

If serial i s set, the value of deiay is automati cally raised to 20. For example, seriali, 24O0n8 
initializesCOM 1 with the default parameters. 

Setsatime-out (in tenthsof asecond) for keyboard input. If no key ispressed for the 
specified time, the first imageis automati cally booted. Similarly, password input isaborted 
if the user isidlefortoo long. Thedefaulttime-out is infinite. 
Turnson alot of progress reporti ng. H igher numbersgi ve more verbose output. If -v is 
additionally specified on the LI LO command line, the level isincreased accordingly. The 
maximum verbosi ty level is 5. 

Additionally, the kernel configurati on parameters append, ramdisk, read-oniy, read-write, root, and vga can be set in the 
global options section. They are used asdefaultsif they aren't specified in the conf iguration sectionsof the respecti ve kernel 
images. 

PER-IM AG E SECTION 

A per-image section starts with either a line 

image=pat hname 

to indicate a file or device containing the boot imageof a Linux kernel or a line 

other=pat hname 

to indicate an arbitrary system to boot. 

In the former case, if an image line specifies booti ng from adevice, then onehasto indicatetherangeof sectorsto bemapped 
usi ng 

range=s t a r t -end 

In th e I atter case (booti nganother system), there are theth ree options: 

ioader=chai n- 1 oader T his specifies the chain loader that should beused. By default, /boot/cnain.b isused. The 

chain loader must be speci fi ed if booti ng from a device other than the first hard or floppy 
disk. 



timeout=t secs 



verbose=l ève 



table=devi ce 



unsafe 



This specifiesthe devicethat contai ns the partition table. The boot loader will not pass 
parti tion information to the booted operati ng system if thisvariableisomitted. (Some 
operating systems h ave other mean sto determinefrom which partition they havebeen 
booted. For example, MS-DOS usually stores the geometry of the boot disk or partition i n 
its boot sector.) N otethat /sbin/mo must bererun if a partition table mapped referenced 
with tabie ismodified. 

Do not access the boot sector at map creation ti me. T his disables some sanity checks, 
includi ng a partition table check. If the boot sector ison a fixed-format floppy disk device, 
usi ng unsafe avoidstheneed to put a readable disk into the drive when runningthemap 
installa-, unsafe and tabie aremutually incompatible. 



In both cases, thefollowing optionsapply: 



label=name 

alias=na me 
lock 

optional 

password=password 
restricted 



The boot loader uses the mai n fi le na me (without itspath) of each i mage specification to 
identify that image. A different namecan beused by setti ng the vari ableiabei. 
A second name for the same entry can beused by specifyingan alias. 
(Seepreviousdescription.) 

Omittheimageif it isnot availableat map creation ti me. Thisisuseful to specify test 
kernels that are not always present. 
P rotect th e i m age by a passwo rd . 

A password isonly required to boot the i mage if parametersarespecified on thecommand 

line (SUCh as single). 



KERNEL OPTIONS 

If the booted imageisa Linux kernel, then onemay passcommand-lineparametersto this kernel. 



append=s t r i ng 
literal=st r i ng 
ramdisk=s i z e 

read-only 

read-write 
root=r oot ■ devi ce 



vga=mode 



Appendstheoptionsspecified to theparameter linepassed to thekernel. Thisistypically 
used to specify parametersof hardware that can 't be entirely autodetected orforwhich 
probi ng may bedangerous. Example append = "nd=64,32,202". 
Likeappend but removesall other options(such as setti ng of the root device). Becausevital 
optionscan be removed unintentionally with uterai, thisoption cannot be set in the 
global options section. 

Thisspecifiesthe size of the optional RAM disk. A valueof zero indicates that no RAM disk 
should becreated. If thisvariableisomitted, the RAM disk sizeconfigured into the boot 
image is used. 

This specifies that the root filesystem should bemounted read-only. Typically, the system 
startup procedure remounts the root filesystem read-write later (such as after fscking it). 
This specifies that the root filesystem should bemounted read-write. 
This specifies the device that should bemounted asroot. If thespecial namecument isused, 
the root device is set to the devi ce on which the root filesystem iscurrently mounted. If the 
roothasbeen changedwith -r, the respective device isused. If the vari able root isomitted, 
the root device setti ng contai ned inthe kernel imageisused. (That is set at compiletime 
usi ng the root dev variablein thekernel makefileand can later bechanged with therdev(8) 
program.) 

This specifies the VGA text mode that should beselected when booti ng. Thefollowing 
vai ues are recogn i zed ( case i s i gn o red ) : 
nomai: Select normal 80x25 text mode, 
extended (or ext): Select 80x50 text mode, 
ask: Stop and ask for user input (at boot time). 

<number >: U se the correspondi ng text mode. A list of availablemodescan beobtained by 
bootingwith vga=ask and pressing Enter. 



moderators 



If this vari able is omitted, theVGA mode setti ng contai ned in the kernel imageisused. 
(That isset at compiletimeusingthesvGA mode variablein the kernel makefileand can later 
bechanged with therdev(8) program.) 

SEEALSO 

iiio(8), rdev(8).TheLILO distribution comes with very extensivedocumentation ofwhich the preceding information isan 
extract. 

28 July 1995 

MAKEDEV.cfg 

MAKEDEv.cfg— Configuration for makedev(8). 
D ESC RIPTIO N 

MAKEDEv.cfg is a text filethat tells makedev(8) whatto do (and equally importantly, what notto do). U nlikeDEviNFo(5), which 
ismeantto be centrai ly mai ntai ned, it containsall locai configuration for a particular site and ali customization.T nere are 
basicallytwo kindsof declaration in thisfile a "class" declaration and an "omit" declaration. 

A class declaration hastheform 

class name : owner group-owner permi ssi ons 

Thissaysthat any devi cespi aced in the speci fi ed class by devinfo should becreated with thisownership and thesepermis- 
sions. A sample entry might be 

class public: root system 0666 

Thissaysthat devices marked public should beowned by root. system and have mode 666. 
An omit declaration hastheform 

omit { devi ce . . . > 

This causesthe specified devices to never becreated, even if explicitly specified. Use cauti on when setti ng this up. Theintent 
isto beableto run makedev update and not haveit create ali sortsof useless devices you'd never use. 

SEEALSO 

MAKEDEV(8), DEVINF0(5) 

Version 1.4, January 1995 

moderators 

moderators— M ail addressesfor moderated U senet newsgroups. 
DESCRIVO N 

TheGetModeratorAddress(3) routine readsthef ile /news/iib/moderators to determine how to reach the moderator of a 
newsgroup. This isused by inews(l) when an unapproved locai posti ng is madeto a moderated newsgroup. 

Thefileis read until a match isfound. Blank linesand lines starti ng with a number sign (#) areignored. Ali other lines 
should consist of two fields separated by a colon. 

The first field is a wiidmat(3)-style pattern. If it matches the name of the newsgroup, then thesecond field istaken to bea 
format stri ng for sprintf (3). This stri ng should haveat most one%s parameter, which will begiven the name of the 
newsgroup with periods transliterated to dashes. 
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Hereisasamplefile 

foo . important : announce-request@foo.com 
f oo. *:%s@mailer. foo.com 
gnu . * :%s@prep . ai . mit . edu 
:%s@uunet. uu.net 

Using thisfile, posti ngsto the moderateci newsgroup in theleft column will besent to theaddressshown in theright 
column: 

foo. important announce-request@foo.com 
foo.x.announce foo-x-announce@mailer.foo.com 
gnu.emacs.sources gnu-emacs-sources@prep.ai.mit.edu 
comp.sources.unix comp-sources-unix@uunet.uu.net 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

inews(l), inn.conf(5), libinn(3), wildmat(3) 



/etc/modules 

/etc/moduies— Kernel modulesto load at boottime. 
D ESC RIPTIO N 

The /etc/moduies fi le contai ns the namesof kernel modulesthat areto beloaded at boottime, oneper line Comments 
begin with a#, and everythingon the li ne after them areignored. 

Debian G N U /L i nux version 0.93 



motd 

motd— M essage of the day. 
D ESC RIPTIO N 

Thecontentsof /etc/motd aredisplayed by ìogin(l) after a successful login but just before it executes the login shell. 

The motd standsfor "messageof the day," and thisfilehasbeen traditionally been used for exactly that. (It requires much less 
disk space than mail to ali users.) 

FILES 

/etc/motd 

SEEALSO 

login(l) issue(5) 

Linux, 29 December 1992 



mtools 

mtoois— T abl e of D 0 S devi ces. 
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DESCRIPTION 

/etc/mtoois.conf and -/.mtooisrc are the configuration filesfor mtoois. Theseconfiguration files descri bethefollowing 
items: 

Global configuration flagsand variables 
Per-driveflagsand variables 
C haracter translation tables 

/etc/mtoois.conf is the system-wide configuration file, and -/.mtooisrc istheuser's private configuration file. 
GENERAL SYNTAX 

The configuration files is madeup of sections. Each section startswith a keyword identifying the section followed by a colon. 
Then follow variable assi gnments and flags. Variableassignmentstakethefollowingform: 

n a me =v a uè 

Flags are Ione keywordswithoutan equal sign and vai ue followingthem. A section either endsattheend of thefileorwhere 
the next section begins. 

Lines starti ngwith a hash (#) arecomments. N ewline characters are equi vai entto whitespace(except whereending a 
comment). The configuration fi le is case insensitive, exceptfor items enclosed in quotes(such asfilenames). 

DEFAULTVALUES 

For most platforms, mtoois contai nsreasonable compi led-in defaults. You usually don't need to bother with the configura- 
tion file if ali you wantto do with mtoois is access your floppy drives. On theother hand, the configuration fileisneeded if 
you also wantto use mtoois to access your hard disk partitionsand dosemu image files. 

GLOBAL VARIABLES 

G lobal variables may be set to 1 or to 0. 
Thefollowing global flags are recognized: 

mtools_skip_check If this is set to 1 , mtoois skipsmost of itssanity checks. Thisisneeded to read some Atari 

disksthat havebeen madewith theearlier ROM s and thatwould not be recognized 
otherwise. 

mtools_fat_compatibility If this is set to 1, mtoois skipstheFAT sizechecks. Somedisks havea bigger FAT than they 

reallyneed. Thesearerejected ifthisoption isnotset. 
mtools_lower_case If this is set to 1, mtoois displays all-uppercase short fi lenames as lowercase. Thishasbeen 

doneto allow a behavior that is consistent with older versi onsof mtoois, which didn't know 

about the case bits. 

Forexample, inserti ng thefollowing lineinto your configuration fi le instructs mtoois to skip the sanity checks: 

MTOOLS_SKIP_CHECK=1. 

Global variables may also beset viatheenvironment: export mtools_skip_check=i. 

PER-DRIVEFLAGSAND VARIABLES 

Per-driveflagsand valuesmay be descri bed in a drive section. A drive section startswith drive dri vei et ter :. 
Then follow variable-value pai rs and flags. 

GENERAL PURPO SE DRIVE VARIABLES 

Thefollowing variables are available: 



file 



Thenameof the fi le or device holding the disk image. Thisismandatory. Thefilename 
should be enclosed in quotes. 
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use_xdf If thisisset to a nonzero value, mtoois also tristo access this disk asan Xdf disk. Xdf isa 

high-capacity format used by OS/2. This is off by default. 

partition Tells mtoois to treat the drive as a partitioned devi ce and to usethegiven partition. Only 

primary partitions are accessible usi ng this method, and they are numbered from 1 to 4. For 
logicai partitions, use the more general offset variable. The partition variableisintended 
for Syquests, ZIP drives, and DO SEM U hdimages. It isnot recommended for hard disksto 
which di rect access to partitions isavailable. 

offset D escri bes where i n the file the M S-DOSfilesystem starts. Thisisuseful for logicai partitions 

in DOSEMU hdimages and for ATARI RAM disks. By default, thisiszero, meaningthat 
thefilesystem starts right at the beginning of the device or file. 

fat_bits Thenumber of FAT bits. Thiscan bei2 or 16. Thisisvery rarely needed becauseit can 

almost alwaysbededuced from information in the boot sector. On thecontrary, describing 
thenumber of fat bits can actually beharmful if you get itwrong. You should only use itif 
mtoois getstheautodetected number of fat bitswrongor if you want to mformat a disk with 
aweird number of fat bits 

Only the file option ismandatory. Theother parameters may beleft out. In that case, a default value or an autodetected 
value isused. 

D RIVE G EOMETRY CO NFIGU RATIO N 

Geometry information describesthephysical characteristicsaboutthedisk. Itshasthreepurposes: 

mformat T he geometry i nformation iswritten into the bootsectorof the newlymade disk. However, 

you may also describe the geometry information on thecommand line. Seemformat(l) for 
details. 

fiitering On someU nices, device nodes only support onephysical geometry. The geometry is 

compared to theactual geometry stored on the boot sector to makesure that this devi ce 
nodeisableto correctly read thedisk. If thegeometry doesn't match, thisdrive entry fails, 
and the next drive entry hearing the same drive letter istried. Seethenext section "Supply- 
ing M ultiple D escriptions for a D rive" for moredetailson supplying several descriptionsfor 
a drive letter. 

If no geometry information issupplied in the configurati on file ali disks are accepted. On 
Linux (and on Sparc), thereexist device nodes with confi gurable geometry (/dev/fdo, /devi 
fdi etc), so filtering isnot needed (and ignored) for disk drives. (mtoois stili doesdo 
fi Iteri ng on piai n fi les (disk images) in Linux: This ismainly intended for test purposes 
becausel don't have access to a U N IX that would actually need filtering.) 
initiai geometry The geometry i nformation (if available) is also used to set the initial geometry on 

confi gurable devi ce nodes. This initial geometry isused to read the boot sector, which 
contai ns the real geometry. If no geometry information issupplied in theconfiguration file, 
no initial configuration isdone On Linux, thisisnot really needed either becausethe 
confi gurable devices are able to autodetect the disk type accurately enough (for most 
common formats) to read the boot sector. 

W rong geometry information may lead to very bizarre errors. That'swhy I strongly recommend that you don't use geometry 
configuration unlessyou really need it. 

T h e f o 1 1 owi ng geom etry rei ated vari abl es are avai I abl e: 
cyiinders T he number of cyli nders. 

neads The number of heads(sides). 

sectors The number of sectors per track. 
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Forexample, thefollowing drivesection describesa 1.44M drive: 
drive a: 

file="/dev/fd0H1440" 
fat_bits=12 

tracks=80 heads=2 sectors=18 

Thefollowing shorthand geometry descriptionsareavailable 



1.44M H igh density, 3 1/2 disk. Equivalenti to fat_bits=i2 tracks=80 heads=2 sectors=i8. 

1.2M H igh density, 5 1/4 disk. Equivalenti to fat_bits=i2 tracks=80 heads=2 sectors=is. 

720K Doublé density, 3 1/2 disk. Equivalenti to fat_bits=i2 tracks=80 heads=2 sectors=9. 

360K Doublé density, 5 1/4 disk. Equivalenti to fat_bits=i2 tracks=40 heads=2 sectors=9. 



The shorthand format descriptionsmay beamended. Forexample, 360K sectors=8 descri besa 320K disk and isequivalentto 

fat_bits=12 tracks=40 heads=2 sectors=8. 

OPEN FLAGS 

M oreover, thefollowing flags are available: 

sync Ali I/O operationsaredonesynchronously. 

nodeiay T he device or fi le is opened with theo_NDELAY flag. Thisisneeded on some non-Linux 

architectures. 

exciusive T he deviceor file is opened with the o_excl flag. On Linux, thisensuresexclusiveaccessto 

the floppy drive. 0 n most other architectures and for plain files, it has no effect at ali. 

SU PPLYING M U LTIPLE D ESCRIPTIO N S FO R A D RIVE 

It is possi bleto supply multi pie descri ptions for a drive In thatcase, the descri ptions are tri ed in order until oneisfound 
thatfits. Descri ptionsmay fail forseveral reasons: 

■ The geometry isnot appropriate 

■ Thereisno disk in thedrive 

■ Other problems 

M ultiple definitions are useful when using physical devicesthat areonly ableto support one single disk geometry: 

drive a: file="/dev/fd0H1440" 1.44m 
drive a: f ile=" /dev/f d0H720" 720k 

Thisinstructs mtoois to use /dev/fd0HH40 for 1.44M (high density) disksand /dev/fd0H720 for 720K (doublé density) disks. 
0 n Linux, this feature is not really needed because the /dev/tdo device is ableto handle any geometry. 

You can also use multi pie drive descriptions to access both of your physical drivesthrough one drive letter: 

drive z: file="/dev/fd0" 
drive z: file=" /dev/f d1 " 

With this descri ption, mdir z: accesses your first physical drive if it contai ns a disk. If the first drive doesn't contai n a disk, 
mtoois checksthesecond drive. 

When using multi pie configuration files, drive descriptions in thefilesparsed last overri de descri ptions for the same drive in 
earlier files. In order to avoid this, usethedrive+ or+drive keywordsinstead of drive. The first adds a descri ption to the end 
of the list (will betried last), and thesecond addsit to the start of the list. 



CHARACTER TRANSLATIO N TABLES 

If you live in the USA, in Western Europe, or in Australia, you can skip this section. 
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INTRODUCTION 

DOS uses a differentcharacter code mapping from UNIX. Ss/en-bit characters stili havethesamemeaning; only characters 
with theeight-bit set areaffected. To makemattersworse, thereareseveral translation tables avai lable dependi ng on the 
country whereyou are. Theappearance of the characters isdefined using codepages. Thesecodepages aren't thesamefor ali 
countries. Forinstance, some code pagesdon't contai n upper -case accented characters. On theother hand, some codepages 
contai n characters that don'texist in U N IX, such ascertain line-drawing characters or accented consonantsused by some 
Eastern European countries. Thisaffectstwo things relating to filenames: 

U ppercase characters In short names, only uppercase characters are al lowed. Thisalso holdsfor accented 

characters. For instance, in a code page that doesn't contai n accented uppercase characters, 
the accented lowercase characters get tran sform ed into their unaccented counterparts 

Longfilenames M icrosoft has final ly comete their sensesand uses a more standard mapping for the long 

filenames. They use U ni code, which is basically a 32-bit version of ASCII. Its first 256 
characters are i denti cai to U N IX ASCII. Thus, the code page also affectsthecorrespondence 
between the codes used i n long names and those used i n short names. 

mtoois considersthefilenamesentered on thecommand lineashavingtheU N IX mapping and translates the characters to 
get short names. By default, code page 850 isused with the Swissuppercase/lowercase mapping. I chosethis code page 
because its set of existi ng characters most closely matches U N I X 's. M oreover, thi s code page covers most characters i n use i n 
the U SA, Australia, and Western Europe. H owever, it is stili possi bleto chose a different mapping. There are two methods: 
the country vari able and expli ci t tables. 

CO NFIGU RATIO N USING COUNTRY 

The country vari able is recommended for people that also have access to M S-D OS system filesand documentation. If you 
don't have access to these l'd suggestyou use explicit tables instead. 

Syntax: COUNTRY=" country [,[ codepage ], country, sys ]" 

Thistells mtoois to use a U N IX-to-D OS translation tablethat matches codepage and an lowercase-to-uppercasetablefor 
country and to use thec ou nt r y . s y s file to get the lowercase-to-uppercasetable. The country code is most often thetelephone 
prefixof the country. Referto the DOS help pageon country for more details. The code page and the c ou nt ry. sys parameters 
are optional. D on'ttypein the square brackets; they are only there to indicate which parameters are optional. The 
count ry. sys fi le is supplied with M S-D OS. In most cases, you don't need it because the most common translation tables are 
compi led into mtoois. Don't worry if you run aU N IX-only box that lacksthisfile 

If codepage isnot given, a per-country default code page isused. If the country, sys parameter isn't given, compi led-in 
defaults are used for the lowercase-to-uppercasetable. Thisisuseful for other U nicesthan Linux, which may have no 
count ry. sys fi le avai lable online. 

TheU N IX-to-D OS are not contai ned in the count ry. sys file, and thus mtoois always uses compi led-in defaults for those 
Thus, only a limited amount of codepages aresupported. If your preferred code page ismissing, or if you know thenameof 
theW indows95 file that contai nsthis mapping, drop me a lineatAiain.KnaffWnriaipes.fr. 

T he country variablecan also be set using the environment. 

CO NFIGU RATIO N USING EXPLICIT TRANSLATION TABLES 

Translation tables may bedescribed in lines in theconfiguration file. Two tables are needed: first the D OS-to-U N IX table 
and then the lowercase-to-uppercasetable. A D OS-to-U N IX table starts with thetounix keyword, fol lowed by a colon and 
128 hexadecimal numbers. A lower-to- upper table starts with thetucase keyword, followed by a colon and 128 hexadecimal 
numbers. 

The tables only show the translati ons for characters whose codes isgreaterthan 128 because translation for lower codes is 
trivial. Example: 
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tounix: 














0XC7 


0xfc 


0xe9 


0xe2 


0xe4 


0xe0 


0xe5 


0xe7 


0xea 


0xeb 


0xe8 


0xef 


0xee 


0xec 


0XC4 


0xc5 


0xc9 


0xe6 


0xc6 


0xf4 


0xf6 


0xf2 


0xfb 


0xf9 


0xff 


0xd6 


0xdc 


0xf8 


0xa3 


0xd8 


0xd7 


0x5f 


0xe1 


0xed 


0xf3 


0xfa 


0xf1 


0xd1 


0xaa 


0xba 


0xbf 


0xae 


0xac 


0xbd 


0xbc 


0xa1 


0xab 


0xbb 


0x5f 


0x5f 


0x5f 


0x5f 


0x5f 


0XC1 


0xc2 


0XC0 


0xa9 


0x5f 


0x5f 


0x5f 


0x5f 


0xa2 


0xa5 


0xac 


0x5f 


0x5f 


0x5f 


0x5f 


0x5f 


0x5f 


0xe3 


0xc3 


0x5f 


0x5f 


0x5f 


0x5f 


0x5f 


0x5f 


0x5f 


0xa4 


0xf0 


0xd0 


0xc9 


0xcb 


0xc8 


0x69 


0xcd 


0xce 


0xcf 


0x5f 


0x5f 


0x5f 


0x5f 


0x7c 


0x49 


0x5f 


0xd3 


0xdf 


0xd4 


0xd2 


0xf5 


0xd5 


0xb5 


0xfe 


0xde 


0xda 


0xd9 


0xfd 


0xdd 


0xde 


0xaf 


0xb4 


0xad 


0xb1 


0x5f 


0xbe 


0xb6 


0xa7 


0xf7 


0xb8 


0xb0 


0xa8 


0xb7 


0xb9 


0xb3 


0xb2 


0x5f 


0x5f 


fucase: 














0x80 


0x9a 


0x90 


0xb6 


0x8e 


0xb7 


0x8f 


0x80 


0xd2 


0xd3 


0xd4 


0xd8 


0xd7 


0xde 


0x8e 


0x8f 


0x90 


0x92 


0x92 


0xe2 


0x99 


0xe3 


0xea 


0xeb 


0x59 


0x99 


0x9a 


0x9d 


0x9c 


0x9d 


0x9e 


0x9f 


0xb5 


0xd6 


0xe0 


0xe9 


0xa5 


0xa5 


0xa6 


0xa7 


0xa8 


0xa9 


0xaa 


0xab 


0xac 


0xad 


0xae 


0xaf 


0xb0 


0xb1 


0xb2 


0xb3 


0xb4 


0xb5 


0xb6 


0xb7 


0xb8 


0xb9 


0xba 


0xbb 


0xbc 


0xbd 


0xbe 


0xbf 


0XC0 


0XC1 


0xc2 


0xc3 


0XC4 


0xc5 


0xc7 


0xc7 


0xc8 


0xc9 


0xca 


0xcb 


0XCC 


0xcd 


0xce 


0xcf 


0xd1 


0xd1 


0xd2 


0xd3 


0xd4 


0x49 


0xd6 


0xd7 


0xd8 


0xd9 


0xda 


0xdb 


0xdc 


0xdd 


0xde 


0xdf 


0xe0 


0xe1 


0xe2 


0xe3 


0xe5 


0xe5 


0xe6 


0xe8 


0xe8 


0xe9 


0xea 


0xeb 


0xed 


0xed 


0xee 


0xef 


0xf0 


0xf1 


0xf2 


0xf3 


0xf4 


0xf5 


0xf6 


0xf7 


0xf8 


0xf9 


0xf a 


0xfb 


0xfc 


0xfd 


0xfe 


0xff 



The first tablemaps DOS character codesto UNIX character codes. For example, the DOS character number 129 isau with 
two dotson top of it. To translate it into U N IX, welook at the character number 1 in the first table (1 =129 - 128). Thisis 
0xfc. (Beware; numbering startsat 0.) Thesecond tablemaps lowercaseDOS charactersto uppercaseDOS characters. The 
samelowercaseu with dotsmapsto character 0x9a, which isan uppercaseU with dots in DOS. 

U N ICO D E CHARACTERS G REATER THAN 256 

If an existing M S-DOS name contai nsU nicode character greater than 256, these are trans! ated to underscoresor to 
characters that are dose in visual appearance. For example, accented consonantsaretranslated into theirunaccented 
counterparts. Thistranslation isused formdir and for the U N IX filenamesgenerated by mcopy. Linux doessupport U nicode 
too, but unfortunately, too few applicationssupport it yet to bother with it in mtoois. M ost i mportantly, xterm can't display 
U nicode yet. If thereissufficient demand, I might include support for U ni code in the U N IX filenamesaswell. 

Caution: W hen deleti ng fi les with mtoois, theunderscorematchesall characters that can't be represented in U N IX. Be 
careful beforemdei! 

LOCATION 0 F CO NFIGU RATIO N FI LES AND PARSING ORDER 

Theconfi guration filesareparsed in thefollowing order: 
Compiled-in defaults 
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/etc/mtools.conf 

/etc/mtoois. Thisisfor backwards compatibility only and isonly parsed if mtoois.conf doesn't exist. 

-/ .mtoolsrc 

0 ptions described in the later files overridethosedescribed in the earlier files. D rives defi ned in earlier files persi st if they are 
not overridden in the later files. For instance, drivesA and B may be defi ned in /etc/mtoois.conf and drivesC and D may be 
defi ned in -/. mtoolsrc. H owever, if -/.mtoolsrc also definesdriveA, thisnew descri ption would override thedescri ption of 
drive A in /etc/mtoois.conf instead of addingto it. If you wantto add a new descri ption to a drive already described in an 
earlier fi le, you need to useeitherthe+drive ordrive+ keywords. 

BACKWARDS COMPATIBILITY 

T he syntax described herein isnew for version mtoois 2.5.4. The old li ne-oriented syntax is stili supported. Each line 
beginningwith a single letter isconsidered to bea drive descri ption using the old syntax. Old styleand new style drive 
sections may bemixed within thesameconfiguration fileto makeupgrading easier. Support for the old syntax wi II bephased 
out eventually, andto discourageitsuse, I purposefully omit itsdescription here. 

FILES 

/etc/mtools.conf 
" / . mtoolsrc 

SEE ALSO 

mtools(l) 

5 Decemberl995 
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newsf eeds— D etermine where U senet articles get sent. 
DESCRI PTION 

Thefile /news/nb/newsteeds specifieshow incomi ng articles should be distributed to other sites. It is parsed by the 
InterN etN ews server innd(8) when it startsup orwhen di rected to by ctimnd(8). 

T he file is interpreted asaset of lines accordi ng to thefollowing rules. If a lineendswith a backslash, then the backslash, the 
newline, and any whitespaceat the start of the next line isdeleted. T his is repeated unti I the enti re "logi cai" lineiscollected. 
If the logicai lineisblank or starts with a number sign (#), it isignored. 

Ali other lines are interpreted asfeed entri es. An entry should consist of four colon-separated fields; two of the fields may 
have optional subfields, marked off by aslash. Fields or subfieldsthat take multiple parameters should beseparated by a 
comma. Extra whitespacecan cause problems. Except for the site names, case i s signif icant. The format of an entry is 

si t e n a me [ /exclude.exc I ud e , . . . ] \ 

: pattern, pat t er n . . . [ /distrib , d stri b . . . J \ 

: f lag , f I ag . . . \ 

:param 

Each field is described below. 

The si tename is the name of the site to which a newsarticlecan besent. It isused forwriting logentriesand for determi ni ng 
if an arti de should beforwarded to a site. If si tename already appears in the arti cle's Path header, then the arti de wi II not be 
sent to the site. The name isusually whatever the remote site usesto identify itself in the Path linebut can bealmost any 
word that makessense; special locai entri es (such as archi vers or gateways) should probably end with an exclamation point to 
makesurethat they do not have the same name as any real site. For example, gateway isan obvious name for the locai entry 
that forwards articles out to a mailing list. If a site with the name gateway postsan article, when the locai site receivesthe 
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arti de, it will seethenamein thePath and notsend the articleto itsown gateway entry. If an entry hasan exclusion subfield, 
then the article will not be sent to that site if any of the names speci fi ed as excludesappear i n the Path header. T he same 
sitenamecan beused morethan once; the appropriate action will betaken foreach site that should receive the article, 
regardlessof thename, although thisisrecommended only for program feedsto avoid confusion. Caseisnot significant in 
site names. 

Thepatter nsspecify which groupsto send to the site and are i nterpreted to build a "subscri ption list" for the site. The 
default subscri ption isto get ali groups. Thepatternsin thefield arewiidmat(3)-style patterns and arematched in order 
against the list of newsgroups that the locai sitereceives. If the first characterof a pattern isan exclamation mark, then any 
groups matching the pattern areremoved from the subscri ption; otherwise, any matching groups are added. For example, to 
receive ali comp groups but only comp.sources.unix within thesources newsgroups, thefollowing set of patterns can beused: 

comp . * , Icomp. sources . *, comp. sources . unix 

There arethreethingsto noteabout thisexample. Thefirst isthatthetrailing .* isrequired. Thesecond isthat, again, the 
resultof thelast match isthemost important. Thethird isthat comp. sources.* could bewritten as comp. sources*, butthis 
would not have the same effect if there were a comp. sources -oniy group. 

Seeinnd(8) for detailson the propagati on of control messages. 

A subscri ption can befurther modified by specifying "distri butions" that the site should or should not receive. The default is 
to send ali articlesto ali sites that subscri beto any of the groups whereit hasbeen posted, but if an article has a D istribution 
header and any distri bs arespecified, then they arechecked accordi ng to thefollowing rules: 

1. If the D istribution header matchesany of thevaluesin the subfield, then the article is sent. 

2. If a di stri b starts with an exclamation point and it matchestheD istribution header, then the article is not sent. 

3. If D istribution header does not match any distri b in the si te's entry and no negationswereused, then the article is not 
sent. 

4. If D istribution header does not match any distri b in the si te's entry and any distri b started with an exclamation point, 
then thearticleissent. 

If an article has morethan onedistribution specified, then each oneisevaluated accordi ng to the precedi ng rules. If any of 
thespecified distributions indicate that the article should besent, it is. If nonedo, it isnotsent: The rules are used asa 
"logicai or." It isalmost definitely a mistaketo haveasinglefeed that specifies di stri butions that start with an exclamation 
pointalongwith somethatdon't. 

Distributions are textwords, not patterns; it isusually a mistaketo have entri eslike* orali there 

Thef i ags parameter specifies miscellaneous parameters. They may be specified in any order; flags that takevalues should 
h ave th e vai ue i m m ed i ately after th e f I ag I etter w i th n o wh i tespace. T h e vai i d f I ags are 

< s i z e An article will only be sent to the site if it is less than s i z e bytes long. Thedefault isno 

limit. 

a c h e c k s An article will only besent to the site if itmeets the requirements specified inthechecks, 

which should bechosen from thefollowing set: 
d D istribution header required 

p Do not check Path header before propagati ng. 

b hi g h /i o w If a site is bei ngfed by a fi le, charme! , or exploder, the server will usually start tryingto write 

the information assoon aspossible Provi di ng a buffer may gi ve better system performance 
and help smooth out overall load if a large batch of newscomes in. Thevalueof thethisflag 
should betwo numbersseparated by a slash. Thefirst speci fi es the poi ntat which the server 
can start draining thefeed's I/O buffer, and thesecond specifies when to stop writing and 
begin buffering again; the uni ts are bytes. Thedefault isto do no buffering, sending output 
assoon asit is possi bleto do so. 

f name T his f I ag specifi es the name of the file that should beused if it is necessary to begin spooling 

for the site. If name is not an absolute pattinarne, it istaken to be relati veto /news/spooi/ 
out. going. Then, if the desti nation is a directory, the fi le to go in that directory will beused 
as filmarne. 



If thisflag is specifi ed, an articlewill only besent to the site if it is posteci to no morethan 
count newsgroups. 

If thisflag is specifi ed, an articlewill only besent to the siteif ithascount orfewersitesin 
its Path line. Thisflag should only beused asarough guide becauseof the loose interpreta- 
tion of the Path header; somesites put theposter'snamein theheader, and somesitesthat 
might logically beconsidered to beone hop becometwo becausethey put theposting 
workstation'snamein theheader. The default valuefor count isone. 
T he flag specifi es the sizeof the internai buffer fora file feed. If there are more file feeds 
than allowed by the system, they wi II bebuffered internally in least recenti y used order. If 
theinternal buffer grows bigger than si ze bytes, however, thedatawill bewritten outtothe 
appropriate file 

The newsgroups that a site receives are modified according to the modifiers, which should 
be chosen from thefollowing set: 
m Only moderated groups 

u 0 nly unmoderated groups 

If the amountof data queued for the site getsto belargerthan si ze bytes, then theserver 
will switch to spooling, appendi ng to a file specifi ed by the f flag or /news/spooi/out.going/ 
si tename if the f flag isnot specifi ed. Spooling usually happens only for channel or exploder 
feeds. 

T his flag specifi es the typeof feed for the site, type should bea letter chosen from the 
following set: 



c Channel 

f File 

1 Log entry only 

m Funnel (multiple entries feed into one) 

p Program 

x Exploder. Each feed isdescribed in thesection on feed types. 



The default isTf. 

If a siteisfed by file, channel, or exploder, thisflag controlswhat information iswritten. If 
a si te i s f ed by a program, only the asterisk (*) hasany effect. The items should be chosen 
from thefollowing set: 



b Sizeof the article in bytes. 

f Article's full pathname. 

g Thenewsgroupthearticleisin; if cross-posted, then the fi rst of the groups 

this si te gets 
m Article's Message-ID. 

n Article's pathname relative to the spool directory, 

p The site that fed thearticleto theserver; from thePath header. 

s ThelP addressof thesitethatsentthearticle 

t Timearticlewasreceived assecondssinceepoch. 

* Namesof theappropriatefunnel entries; orali si tes th at get th e arti ci e. 

d Valueof the Di stributi on header; ? if none present. 

h Ali headers. 

n Valueof the Newsgroups header. 

o 0 vervi ew data. 

r Information needed for replication. M ore than one letter can beused; the 

entries will beseparated by a space and written in the order in which they are 
speci fi ed. The default iswn. 
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TheH and o itemsareintended for useby programsthat create newsoverview databases. I f h 
ispresent, then theall the arti cle's headers are written followed by a blank line. An Xref 
header (even if onedoes not appear in thefiled article) and a Bytes header, specifying the 
article'ssize, will also bepart of the headers. If used, this should betheonly item in the list; 
if preceded by otheritems, however, a newline will bewritten before the headers. Theo 
generates inputto theoverchan(8) program. It, too, should betheonly item in the list. 
Theasterisk has special meaning. It expandsto a space- separated list of ali sitesthat received 
thecurrent article. If the site i s the target of afunnel, however (thatis, itisnamed by other 
sitesthat nave arni flag), then theasterisk expandsto thenamesof thefunne! feedsthat 
received the article. If the site isfed by a program, then an asterisk in theparam field will be 
expanded into the list of funnel feedsthat received the article. A site fed by a program 
cannot get the site list uni ess it is the target of other t™ feeds. 

Theinterpretation of theparam field dependson thetypeof feed, and isexplained in moredetail in thesection on feed types. 
Itcan beomitted. 

The site named me i s special. There should only beone such entry, and it should bethefirst entry in the fi le. If the me entry 
hasasubscription list, then that list isautomatically prepended to the subscription list of ali other entries. For example, 
*,! control, ! junk, if oo.* can beused to set up theinitial subscription list for ali feeds so that locai posti ngs are not propa- 
gated unless too.* explicitly appears in the site's subscription list. N otethat most subscriptions should have ! junk, icontroi 
in their pattern list; seethediscussion of control messages in innd(8). (U nlike other news software, it doesnot affect what 
groups are received; that is done by the active(5) file.) 

If the me entry has a distri bution subfield, then only arti cles that match thedistri bution list are accepted; ali other arti cles are 
rejected. A commercial news server, for example, might have /! locai to reject locai posti ngs from other, misconfigured, sites. 

FEED TYPES 

innd providesfour basic types of feeds: log, file, program, and channel. An exploder is a special typeof channel. In addi ti on, 
several entries can feed into the same feed; these are funnel feeds, which refer to an entry that isoneof the other types. N ote 
that the term "feed" istechnically a misnomer because the server doesnot transfer articles but reports that an article should 
besent to the site. 

T he si m pi est feed isonethat isfed by a log entry. Other than a mention in the news logfile, no data isever written out. This 
isequivalent to aTf entry writing to /dev/nuii except that no fi le is opened. 

A site fed by a file i s si m pi est type of feed. When the site should receivean article, one line is written to the fi le named by the 
p a r a m field. If par am isnotan absolute pathname, itistaken to be relative to /news/spooi/out.going. If empty, thefilename 
defaultsto /news/spooi/out.going/si t ena me . T his name should beunique 

When a si te fed by afileisflushed (see ctiinnd), thefollowing steps are performed. The script doingtheflush should have 
first renamed the fi le. The server tri esto writeout any buffered data and then closesthefile. Therenamed fileisnow 
available for use. The server will then reopen the originai file, which will now get created. 

A site fed by a program hasaprocessspawned for every article that the site receives. Theparam field must bea sprintf(3) 
format stri ng that may haveasingle%s parameter, which will begiven a pathname for the article, relati veto the news spool 
directory. The full pathname may beobtai ned by prefixing the%s in thepar am field by the news spool directory prefix. 
Standard input will beset to the article or /dev/nuii if the article cannot be opened for somereason. Standard output and 
error will beset to the errar log. The process will run with the user and group ID of the/news/iib/mnd directory, innd will 
try to avoid spawningashell if thecommand hasno shell meta-characters; this feature can bedefeated by appendinga 
semi colon to the end of thecommand. The full pathname of the program to berun must be specified; for security, path is 
not searched. 

If the entry is the target of afunnel, and if thew* flag isused, then a single asterisk may beused in theparam field whereit 
will bereplaced by thenamesof the sites that fed into the funnel. If theentry is not a funnel, or if thew* flag is not used, 
then the asterisk has no special meaning. 
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Flushing a sitefed by a program does no action. 

When a site is fed by achannel or exploder, the par a m field namestheprocessto start. Again, the full pathnameof theprocess 
must begiven. When the site isto receivean article, theprocess receivesa lineon its standard input tei li ng it aboutthe 
article Standard output and error and the user and group ID of the ali subprocessare set asfor a program feed. If theprocess 
exits, itwill berestarted. If theprocess cannot bestarted, the server will spool input to afilenamed /news/spooi/out.going/ 
si tename . It will then try to start theprocess some ti me later. 

When a si te fed by a channel or exploder isflushed, the server closesdown its end of the pipe. Any pendi ng data that hasnot 
been written will bespooled; seethedescription of thesflag. N o signal issent; it isup to the program to noticeEOF on its 
standard input and exit. The server then startsa new process. 

Explodersareasuperset of channel feeds. In addition to channel behavior, exploderscan besent command lines. Theselines 
start with an exclamati on point, and their interpretati on isup to the exploder. Thefollowing messagesaregenerated 
automati cai ly by the server: 

newgroup group 
rmgroup group 
flush 
flush site 

Thesemessages are sent when thectiinnd command of thesamenameisreceived by the server. In addition, the sena 
command can beused to send an arbitrary command lineto the exploder chi Id-process. The primary exploder isbuffchan(8). 

Funnel feeds provi de a way of merging several site entries into a single output stream. For asitefeeding into afunnel, the 
paramfield names the actual entry that does the feeding. 

For more detailson setti ng up differenttypesof news feeds, seetheINN installation manual. 
EXAMPLES 

## Initial subscription list and our distributions . 
ME:*, !j unk, !foo.*/world,usa,na,ne,foo,ddn,gnu,inet\ 

## Feed ali moderated source postìngs to an archìver 

source-archive! : !*,comp.sources.*\ 

:Tp,Nrn: /usr/local/bin/archive %s 

## Watch for big postings 

watcher! :*\ 

:Tc,Wbnm\ 

:exec awk '$1 > 1000000 { print "BIG" , $2, $3 }' >/dev/console 

## A UUCP feed, where we try to keep the "batching" between 4 and 1K. 

ihnp4: /world, usa, na,ddn,gnu\ 

:Tf ,Wfb,B4096/1024: 

## Usenet as mail; note ! in funnel name to avoid Path conflicts. 
## Can't use ! in "fred" since it would like look a UUCP address. 
fred: !*,comp.sources.unix,comp.sources.bugs\ 
:Tm: mailer! 

barney9bar.com: ! *, news . software. nntp ,comp . source s.bugs\ 
:Tm: mailer! 
mailer! : ! *\ 

:W* ,Tp : /usr/ucb/Mail -s "News article" * 

## NNTP feeds fed off-line via nntpsend or equivalent. 

feedl : :Tf ,Wnm:feed1 .domain. name 

peer .f oo . com : f oo . * :Tf ,Wnm: peer.foo.com 

## Real-time transmission . 

mit.edu: /world, usa, na, ne, ddn, gnu, inet\ 

:Tc,Wnm: /nntplink -i stdin mit.edu 

## Two sites feeding into a hypothetical NNTP fan-out program: 

nic.near.net : \ 

:Tm:nntpfunnel1 
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uunet.uu.net/uunet: Ine. */world, usa,na,f oo,ddn,gnu,inet\ 
:Tm:nntpfunnel1 
nntpf unnell : ! *\ 
:Tc,Wmn* : /nntpfanout 

## A UUCP site that wants comp.* and moderated soc groups 
uucpsite! comp: !*, comp. */world, usa, na, gnu \ 
:Tm:uucpsite 

uucpsite !soc: !*,soc.*/world,usa,na,gnu\ 
:Tm,Nm:uucpsite 
uucpsite: !*\ 

:Tf ,Wfb: /usr/ spool /batch /uucpsite 

Thelasttwo setsof entri es show how funnel feadscan beused. Forexample thenntpfanout program would receive lines like 
thefollowingon its standard input: 

<123@litchi.f oo.com> comp/sources/unix/888 nic.near.net uunet.uu.net 
<124@litchi.f oo.com> ne/general/1003 nic.near.net 

BecausetheUUCP funnel isonly desti ned for onesite, theasterisk isnot needed and entri es like the following will be 
written into thefile: 

<qwe#37x?snar k.uu. net >comp/ society /folklore/3 
<123@litchi .f oo . com> comp/sources/unix/888 

HI STORY 

W ritten by Rich $alz (rsaizuuunet.uu.net) for InterN etN ews. 
SEEALSO 

active(5), buffchan(8), ctlinnd(8), innd(8), wildmat(3) 
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newslog— D escripti on of Usenet logfiles. 
DESCRIPTION 

M ost logfiles created by Usenet programsresidein the/var/iog/news directory and havea .log extension. Several versions 
areusually kept with an additi onal extension such as .1, .2, and so on; thehigherthenumber, the older the log. T he older 
versionsare compressed. 

Thescaniogs script and related Utilities (seenewsiog(8)) are responsiblefor rotating and compressing thesefiles. 

Some log files always have data, othersonly havedata if thereisa problem, and othersareonly created if aparticular 
program isused or confi guration parameter isset. Theinnstat script (see newsiog(8)) monitorsthesizeof ali logfiles. 

The following files will only accumulate data under the direction of control. cti(5): 

control.log, miscctl.log, newgroup.log, rmgroup.log, unwanted.log 

In orderto create thesefiles, themessage and action fieldsof control. cti should bechosen from thefollowing table: 

Message Action Meaning 

ali iog=misccti Log ali messages by default 

default iog=misccti Log unknown messages 

newgroup doit=newgroup C reate group and log message 

newgroup log=newgroup Log message 
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M essage 


Action Meaning 


rmgroup 


doit=™group Removegroup and log message 


rmgroup 


iog=rmgroup Log message 


"other" 


doit=misccti Log and process the message 


"other" 


iog=misccti Log message 


H ere, "other" refersto any other control message such as: 


checkgroups ihave sendme 


sendsys senduuname version 


Thefollowing isa list of logfiles. 


control.log 


Thisfilemaintainsacount of thenumber of newgroup and rmgroup control messagesseen for 




each newsgroup. Thecount isof the number of control messageswith identical arguments, 




regardless of whether they were actually processed. AH control arguments, including invalid 
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errlog 
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control. T hi s fi le should beempty. Scanlogswill print the enti re contents of this log file if it 




is non-empty. 


expire . log 


By default, when news.daiiy isgoingto expireold newsarticles, itwrites the date to this 




file, followed by any output from expire(8) and theending date Ali linesbut the first are 




indented four spaces. 


miscctl . log 


When control. cti isconfigured asdescribed above, ali control messagesexcept newgroup 




and rmgroup areappended to thisfileby writeiog.Therewill beasummary line describi ng 




themessageand theaction taken, followed by the article indented by four spaces and a 




blank line. 


newgroup.log 


When control. cti isconfigured asdescribed above, ali newgroup messages areappended to 




thisfileusingthesameformatasformisccti.log. 


news 


This file logsarticles received by innd. scaniogs summarizestherejected articles reported in 




thisfile. 


news.crit 


Ali criticai errar messages issu ed by innd are appended to this fi le via sysiog(3). T hi s log file 




should beempty. scaniogs will pri nt the enti re contents of this log file if it is non-empty. 




You should have thefollowing line in your sysiog.cont(5) file: 




news.crit /var/ log /news /news.crit 


news . err 


Ali major errar messages issu ed by innd areappended to thisfile via sysiog. This log file 




should beempty. scaniogs will pri nt the enti re contents of this log file if it is non-empty. 




You should have thefollowing linein your sysiog. conf file 




news. err /var/log/news/news . err 


news . notice 


Ali standard errar messages and status messages issu ed by innd areappended to this fi le via 




sysiog. scaniogs usestheawk(l) script inniog.awk to summarize thisfile You should have 




thefollowing line in your sysiog. conf file: 




news. notice /var/log/news/news . notice 


nntpsend.log 


Thenntpsend(8) programs appends ali status messages to thisfile. 


rmgroup.log 


When control. cti isconfigured asdescribed previously, ali rmgroup messages are appended 




to this fi le usi ng the same format as for misccti . log. 


unwanted.log 


This log maintains a count of the number of articles that were rejected because they were 




posted to newsgroupsthat do not exist at the locai site. This file isupdated by 




taiiy.unwanted and maintained in reverse numeric order (the most popular rejected group 




f i rst) . T h i s f i 1 e i s not rotated . 



HI STORY 

Written by Landon Curt N oli (chongo@toad.com) and Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

control. ctl(5), ctlinnd(8), expire(8), innd(8), news.daily(8), nntpsend(8), newslog(8) 



nfs 



nfs— N FS fstab format and options. 
SYNOPSIS 

/etc/fstab 

D ESC RIPTIO N 

The fstab fi le contai nsinformation about which filesystemsto mount whereand with what options. For N FS mounts, it 
contai ns the server nameand exported server directory to mount from, the locai directory thatis the mount point, and the 
N FS-specific options that control theway thefilesystem ismounted. H ereisan examplefrom an /etc/fstab filefrom an 
N FS mount. 

server: /usr/local/pub /pub nfs rsize=8192,wsize=8192, timeo=14, intr 



OPTIONS 

rsize=n 



timeo=n 



retrans=n 

acregmin=n 
acregmax=n 
acdirmin=n 
acdirmax=n 
actimeo=n 



Thenumber of bytes N FS useswhen readingfilesfrom an N FS server. The default value is 
dependent on the kernel, currently 1024 bytes. (H owever, throughput isimproved greatly by 
askingfor rsìze=8i92.) 

Thenumberof bytes N FS useswhen writingfilesto an N FS server. The default value is 
dependent on the kernel, currently 1024 bytes. (H owever, throughput isimproved greatly by 
askingforwsize=8i92.) 

The value in tenthsof asecond beforesending the first retransmission after an RPC ti me 
out. The default value is 7 tenthsof asecond. After the first ti me-out, thetime-out is 
doubled after each successive time-out until a maximum ti me-out of 60 seconds isreached 
or theenough retransmissionshaveoccurred to cause a major time-out. Then, if the 
filesystem ishard mounted, each new time-out cascaderestartsattwice the initial value of 
thepreviouscascade, again doubling at each retransmission. The maximum time-out is 
always60 seconds. Betteroverall performance may beachieved by increasi ng the ti me-out 
when mountingon a busy network, to aslow server, or through several routersor gateways. 
The number of minor ti me-outs and retran smissions that must occur before a major time- 
out occurs. The default i s 3 ti me-outs. W hen a major time-out occurs, thefileoperation is 
either aborted or a "server not responding" messageisprinted on the console. 
The minimum ti me in seconds that attributesof a regular fi le should becached before 
requesti ngfresh informati on from a server. The default is 3 seconds. 
The maximum ti me in seconds that attributesof a regular filecan becached before 
requesti ngfresh informati on from a server. The default is 60 seconds 
The minimum timein seconds that attributesof a directory should becached before 
requesti ngfresh informati on from a server. The default is 30 seconds 
The maximum timein seconds that attributesof a directory can becached before requesti ng 
fresh information from a server. The default is 60 seconds 

U Sing actimeo SetS al I Of acregmin, acregmax, aedirmin, and aedirmax tO the Same value. There 

is no default value 
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retry=n 
namlen=n 

port=n 

mountport=n 

mounthost=name 

mountprog=n 

mountvers=n 

nf sprog=n 

nf svers=n 

fg 

soft 
hard 
intr 

posix 

nodo 
noac 

top 
udp 



Thenumberof ti mesto retry a backgrounded N FS mount operation before givi ng up. The 
default value is 10000 times. 

When an N FS server does not support version 2 of theRPC mount protocol, thisoption 
can beused to specify themaximum length of a filenamethat is supported on the remote 
filesystem. This isused to support the POSIX patnconf functions. The default ÌS255 
characters. 

The numeri c value of theport to connectto theN FS server on. If theport number ÌS0 (the 

default) then query the remote host's port mapper for the port number to use. If the remote 

host'sN FS daemon isnot registered with itsport mapper, the standard N FS port number 

2049 isused instead. 

The numeri c value of the mountd port. 

The name of the host running mountd. 

Usean alternate RPC program number to contact the mount daemon on the remote host. 
Thisoption isuseful for hoststhatcan run multiple N FS servers. T hedefault value is 
100005, which isthe standard RPC mount daemon program number. 
U se an alternate RPC version number to contact the mount daemon on the remote host. 
Thisoption isuseful for hoststhatcan run multiple N FS servers. T hedefault value is 
version 1. 

Usean alternate RPC program number to contact the N FS daemon on the remote host. 

Thisoption isuseful for hoststhatcan run multiple N FS servers. T hedefault value is 

100003, which isthe standard RPC N FS daemon program number. 

Usean alternate RPC version number to contact theN FS daemon on the remote host. This 

option isuseful for hoststhat can run multiple N FS servers. T he default value is version 2. 

If the first N FS mount attempt ti mesout, conti nuetrying the mount in the background. 

The default isto not to background the mount on time-out but to fail. 

If the first N FS mount attempt times out, fail immediately. This isthe default. 

If an N FS fi le operation has a major time-out, then report an I/O error to the calli ng 

program. The default isto continue retrying N FS fi le operations i ndefinitely. 

If an N FS fi le operation has a major time-out, then report "server not responding" on the 

consoleand continue retrying indefinitely. This isthe default. 

If an N FS fi le operation has a major time-out and it ishard mounted, then allow signalsto 

interrupt the fi le operation and cause itto return eintr to the cali ing program. The default 

isto not allow fi le operations to beinterrupted. 

M ounttheN FS filesystem using POSIX semantics. Thisallowsan N FS filesystem to 
properly support the PO SIX patnconf command by querying the mount server for the 
maximum length of afilename. To do this, the remote host must support version 2 of the 
RPC mount protocol. Many NFS servers support only version 1. 
Suppress the retri eval of new attributeswhen creati ng a file. 

D isableall formsof attribute cachi ng enti rely. This extracts a server performance penalty, 
but itallowstwo different N FS clientsto get reasonably good resultswhen both clientsare 
actively writingto a common filesystem on the server. 

M ounttheN FS filesystem using theTCP protocol instead of the default UDP protocol. 
M any N FS severs only support UDP. 

M ounttheN FS filesystem using the U D P protocol. This isthe default. Ali thenon-value 
optionshavecorrespondingnooption forms. Forexample, nointr meansdon't allow file 
operations to beinterrupted. 



FILES 

/etc/fstab 



nnrp.acces 



SEEALSO 

fstab(5), mount(8), umount(8), exports(5) 

AUTHOR 

Rick Sladkey (jrs9world.std.com) 

BUGS 

Thebg, fg, retry, posix, and nocto opti ons are parsed Py mount Put currently are silently ignored. Thetcp and namien 
optionsareimplemented Put arenot currently supported PytheLinux kernel. The umount command should notify the server 
when an N FSfilesystem isunmounted. 

Linux 0.99, 20 N ovember 1993 



nnrp. access 

nnrp. access— Access filefor on-campusN NTP sites. 
DESCRIVO N 

Thefile /news/nb/nnrp. access specifies the access control forthoseN NTP sites that arenot handled Pythemain 
InterN etN ewsdaemon innd(8). Thennrpd(8) server reads it when first spawned Py ìnnd. 

CommentsPegin with a numPer sign (#) and conti nuethrough the end of the line. Blank linesand comments are ignored. 
Ali other lines should consist of fivefields separateci Py colons 

h o s t s : p e r ms : u s e r n a me : p a s s wo r d : p a 1 1 e r n s 

Thefirst field is a wiidmat(3)-style pattern specifyi ng the names or Internet addressof a set of hosts. Beforeamatch is 
checked, theclient'shostname(or its Internet addressif gethostbyaddr(3) fails) isconverted to lowercase. Each lineis 
matched in turn, and thelast successful match istaken asthecorrectone. 

Thesecond field is a set of letters specifying the permissions granted to theclient. Theper ms should Pechosen from the 
following set: 

r T he ci i ent can retri ève arti ci es 

p Theclient can post arti cles 

Thethird and fourth fields specify the use ma me and pass word that the eli ent must useto aumentiate themselves Peforethe 
server will accept any articles. Note that no authentication (other than a matching entry in thisfile) is required for 
newsreading. If they areempty, then no password is required. Whitespacein these fields will result in theclient Peing unaPle 
to properly aumentiate themselves and may Pe used to disaPle access. 

Thefifth field is a set of patternsidentifying the newsgroups that the eli ent isallowed to access T he pat ter ns areinterpreted 
in thesamemannerasthenewsfeeds(5) file. The default, however, denies access to ali groups. 

T he access file is normally used to provide host-level access control for reading and posti ng articles. Therearetimes, however, 
when thisis not suffici ent and user-level access control is needed. Whenever an N NTP authinfo command isused, thennrpd 
server rereadsthisfileand looksfor a matching username and password. If the locai newsreadersaremodified to send the 
authinfo command, then ali host entriescan haveno access and specific userscan Pe granted the appropri ateread and post 
access. For example: 

## host:perm:user:pass:groups 
## Default is no access. 
: : -no- : -no- : !* 

## F00 hosts have no password, can read anything. 
.foo.com: Read Post: : :* 

## A related workstation can't access FOO newsgroups. 
lenox.foo.net : RP :martha: hiatt : * , ! f oo . * 
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If the fi I e contai ns passwords, it should notbeworld-readable. 
HI STORY 

Written by Rich $alz (rsaizguunet.uu.net) for InterN etN ews. 
SEEALSO 

innd(8), newsfeeds(5), nnrpd(8), wildmat(3) 

nntpsend.ctl 

nntpsend.ctl— List Of Sites tO feed via nntpsend. 

DESCRIPTION 

The fi le /news/lib/nntpsend.ctl Specifies the default list Of Sites tO befed by nntpsend(8). 

Commentsbegin with a number sign (#) and conti nuethrough the end of the line. Blank linesand commentsareignored. 
Ali other lines should consistof fourfieldsseparated by a colon. 

Thefirst field isthenameof the site as speci fi ed in the newsfeeds(5) file 

Thesecond fi dd should bethehostnameor IP addressof the remote site. 

Thethird field, if non-empty, specifies the default tail truncation sizeof site'sbatchfile. This ispassed to stirimene asthe-s 
flag. If thisfield isempty, no truncation isperformed. 

Thefourth field specifies some default flags passed to innxmit(8). Theflag -a isalwaysgiven to innxmit and need not appear 
here. If no -t ti me o u t flag isgiven in thisfield and on the nntpsend command line, -t isa wi II begiven to innxmit. 

HI STORY 

Written by Landon Curt N oli (chongo@toad.com) for InterN etN ews. 
SEEALSO 

innxmit(8), newsf eeds(5), nntpsend(8), trunc(l) 



nologin 

noiogin— Prevent usuai usersfrom logging into thesystem. 



DESCRIPTION 

If the fi le /etc/noiogin exists, ìogin(l) will allow accessonly to root. Other userswill beshown thecontentsof this fi le and 
their logins refused. 

FILES 

/etc/nologin 

SEEALSO 

login(l), shutdown(8) 

Linux, 29 December 1992 



overview.fmt 

overview.fmt— Format of newsoverview database. 



pasBwd 
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DESCRIVO N 

The fi le /news/iib/overvìew.fmt speci fi es the organi zation of the news o vervi ew database. Blank linesand lines beginning 
with a number sign (#) areignored. Theorder of lines in thisfileis important; it determi nes the order in which the fi elds wi II 
appear in the database. 

M ost I i nes wi II consist of an articleheader name, optionally followed by a colon. A trai li ng set of lines can have the word full 
appear after the colon; thisindicatesthattheheader should appear aswell asitsvalue. 

If thisfileis changed, it is usuai ly necessary to rebuild theexisting overview database usi ngexpireover(8) after removing ali 
existingoverviewfiles. 

The default fi le, show here, iscompatiblewith Geoff Collyer'snov package: 

Subject: 

Frolli: 

Date: 

Message-ID: 
Ref erences : 
Bytes : 
Lines : 

## Some newsreaders get better performance if Xref is present 
#Xref :full 

HI STORY 

Written by Ri eh $alz(rsaiz@uunet. uu.net) for InterN etN ews. Intended to be compati ble with thenov package written by 

Geoff Collyer (geoffeworld.std.com). 



passwd 

passwd— Password file 
DESCRIPTION 

passwd isan ASCII filethatcontainsa list of thesystem'susersand thepasswordsthey must use for access. The password file 
should have general read permission (many Utilities, such asis(l), useitto map user ID sto usernames) butwrite access only 
forthesuperuser. 

In thegood old days, therewas no great problem with this general read permission. Everybody could read theencrypted 
passwords, but the hardware wastoo slow to crack a well-chosen password, and moreover, the basic assumption used to be 
that of a friendly user community. These days, many peoplerun someversion of theshadow password suite, where /etc/ 
passwd has*sinstead of passwords, and theencrypted passwords are in /etc/sbadow, which isreadableby root only. 

When you create a new login, leave the password field empty and usepasswd(l) to fili it. A star (*) in the password field 
means that this user cannot log in via ìogin(l). 

There isone entry per line, andeach line has the format: 

o g i n_ na me : passwd :UI D : G I D:user_name :di r ect or y :s he I 

Thefield descriptionsare 



o g i lì _ name 


The name of the user on the system. 


password 


Theencrypted optional user password. 


Ul D 


The numeri cai user ID . 


Gl d 


The numeri cai grouplD for this user. 


u s e r _ n a me 


T he (optional) comment field (often afull username). 


di r ect or y 


Theuser's$HOME directory. 


shel 1 


Theprogram to run at login (if empty, use /bin/sb). 
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NOTE 

If your root fi le system ison /dev/ram, you must saveachanged password fileto your root fi I esystem floppy beforeyou shut 
down the system and check the access rights. If you wantto create user groups, their GIDsmust beequal and theremust be 
an entry in /etc/group, or no group will exist. 

FILES 

/etc/passwd 



SEEALSO 

passwd(l), login(l), group(5), shadow(5) 

Linux, 24 J uly 1993 



passwd.nntp 

passwd.nntp— Passwordsfor connecting to remote N N TP servers. 
D ESC RIPTIO N 

The fi le /news/iib/passwd.nntp contai ns host-name- password tripletsfor usewhen aumenti cating eli ent programsto N NTP 
servers. Thisfile is normally interpreted by theNNTPsend-password routinein iibinn(3). Blank linesand lines beginningwith 
a number sign (#) areignored. AH other lines should consist of three or fields separateci by colons: 

host : n a me : p a s s wo r d 

host :name : p a s s wo r d : s t y I e 

The first field isthenameof a host and ismatched in acase-insensitivemanner. Thesecond field isausername, and the 
third isa password. Theoptional fourth field specifi es the type of authentication to use Thedefault isauthinfo, which 
meansthat N NTP authinfo commandsareused to auth enti cateto the remote host. If either theusernameor password are 
empty, then the related command will not besent. (Theauthinfo command isacommon extension to RFC 977.) For 
example: 

## UUNET needs a password, MIT doesn't. 

mit.eduibbn: : authinfo 

uunet . uu . net : bbn : yoyoma : authinfo 

Thisfile should not beworld-readable. 
HISTORY 

Written by Ri eh $alz(rsaiz@uunet. uu.net) for InterN etN ews. 
SEEALSO 

innd(8), libinn(3) 



pbm 

pbm— Portable bitmap fileformat. 
D ESC RIPTIO N 

The portable bitmap format isa lowest common denominator monochrome fi le format. It was ori ginally designed to makeit 
reasonableto mail bitmapsbetween differenttypesof machinesusingthetypical stupid network mailerswehavetoday. Now 
it servesas the common languageof a largefamily of bitmap conversi on filters. The definition isasfollows: 

A "magic number" for identifyi ng the file type. A pbm fi le's magic number isthetwo characterspi. 



pgm 



FI 



Whitespace(blanks, Tabs, CRs, LFs). 

A width, formattai as ASC 1 1 charactersin decimai. 

Whitespace. 

A height, again in ASCII decimai. 
Whitespace. 

Width * height bits, each either 1 ora, starti ng atthetop-left corner of thebitmap, proceeding in normal English reading 
order. 

Thecharacter 1 meansblack; 0 meanswhite. 

Whitespace in the bits section isignored. 

C haracters from a # to the next end-of-line are ignored (comments). 

N 0 line should belonger than 70 characters. 

H ereisan exampleof asmall bitmap in this format: 
pi 

# feep.pbm 



1 1 1 
000 
1 1 0 



1 1 1 

0 0 0 

1 1 0 
000 
1 1 1 



111001111 
000001001 
110001111 
000001 000 
111001000 



Programsthat read this format should beaslenient as possi ble, accepting anythingthat looks remotely like a bitmap. 

Thereisalso a varianton the format, availableby setti ng the rawbits option at compi le ti me. Thisvariant isdifferent in the 
followingways: 

The"magic number" is P4 instead of pi. 

The bits are stored eight per byte, high bit first and low bit last. 

N 0 whitespace is al lowed in the bits section, and only a single character of whitespace (typi cai ly a newline) isallowed after 
the height. 

T he files are eight times smaller and many timesfaster to read and write 
SEEALSO 

atktopbm(l), brushtopbm(l), cmuwmtopbm(l), g3topbm(l), gemtopbm(l), icontopbm(l), macptopbm(l), mgrtopbm(l), pi3topbm(l), 
xbmtopbm(l), ybmtopbm(l), pbmto10x(l), pnmtoascii(l), pbmtoatk(l), pbmtobbnbg(l), pbmtocmuwm(l), pbmtoepson(l), pbmtog3(l), 
pbmtogem(l), pbmtogo(l), pbmtoicon(l), pbmtolj(l), pbmtomacp(l), pbmtomgr(l), pbmtopi3(l), pbmtoplot(l), pbmtoptx(l), 
pbmtox10bm(l), pbmtoxbm(l), pbmtoybm(l), pbmtozinc(l), pbmlife(l), pbmmake(l), pbmmask(l), pbmreduce(l), pbmtext(l), 
pbmupc(l), pnm(5), pgm(5), ppm(5) 

AUTHOR 

Copyright 1989, 1991 byjef Poskanzer. 

27 September 1991 



pgm 

pgm— Portable graymap fi le format. 
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DESCRIVO N 

Theportablegraymap format isa lowest common denomi nator grayscale fi le format. The defini tion isasfollows: 

A "magic number" for identifying the file type. A pgm fi le's magic number isthetwo characters P2. 

Whitespace(blanks, Tabs, CRs, LFs). 

A width, formatted asASCII charactersin decimai. 

Whitespace. 

A height, again in ASCII decimai. 
Whitespace. 

Themaximum grayvalue, again in ASCII decimai. 
Whitespace. 

Width * height gray values, each in ASCII decimai, between 0 and the specified maximum value, separated by whitespace, 
starti ng atthetop-left corner of the graymap, proceeding in normal English readingorder. A value of 0 meansblack, and the 
maximum value meanswhite 

C haracters from a # to the next end-of-line are ignored (comments). 
N 0 line should belonger than 70 characters. 

H ere i san exampleof asmall graymap in this format: 

P2 

# feep.pgm 
24 7 

15 



333300777700 
300000700000 
333000777000 
300000700000 
300000777700 



11 1111 0 0 15 1515 15 0 
0 0 0 0 0 15 0 0 150 
11 110 0 0 15 15 15 150 
00000 15 0000 
11 1111 0 0 15 0 0 0 0 



Programsthat read this format should beaslenient as possi ble, accepting anythingthat looks remotely like a graymap. 

Thereisalso a varianton the format, availableby setti ng the rawbits option at compi le ti me Thisvariant isdifferent in the 
followingways 

The"magic number" ìsps instead of P2. 

The gray values are stored asplain bytes, instead of ASCII decimai. 

N 0 whitespace is al lowed in thegrayssection, and only a single character of whitespace (typically a newl ine) isallowed after 
themaxval. 

T hefiles are smaller and manytimesfasterto read andwrite. 



N otethat this raw format can only beused for maxvals lessthan or equal to 255. If you use the pgm library and try to writea 
filewith a larger maxval, it will automati cai ly fall back on theslower but more general plain format. 

ALSO 

fitstopgm(l), fstopgm(l), hipstopgm(l), lispmtopgm(l), psidtopgm(l), rawtopgm(l), pgmbentley(l), pgmcrater(l), pgmedge(l), 
pgmenhance(l), pgmhist(l), pgmnorm(l), pgmoil(l), pgmramp(l), pgmtexture(l), pgmtof its(l), pgmtofs(l), pgmtolispm(l), 



AUTHOR 

Copyright 1989, 1991 byjef Poskanzer. 



12 Novemberl991 




pnm 

pnm— Portable anymap fi le format. 
D ESC RIPTIO N 

The pnm programs operate on portable bitmaps, graymaps, and pixmaps produced bythepbm, pgm, and ppm segments. Thereis 
no fi le format associated with pnm itsdf. 

SEEALSO 

anytopnm(l), rasttopnm(l), tif f topnm(l), xwdtopnm(l), pnmtops(l), pnmtorast(l), pnmtotif f (1), pnmtoxwd(l), pnmarith(l), 
pnmcat(l), pnmconvol(l), pnmcrop(l), pnmcut(l), pnmdepth(l), pnmenlarge(l), pnmfile(l), pnmflip(l), pnmgamma(l), pnmindex(l), 
pnminvert(l), pnmmargin(l), pnmnoraw(l), pnmpaste(l), pnmrotate(l), pnmscale(l), pnmshear(l), pnmsmooth(l), pnmtile(l), 
ppm(5), pgm(5), pbm(5) 

AUTHOR 

Copyright 1989, 1991 byjef Poskanzer. 

27 September 1991 



ppm 

ppm— Portable pixmap fileformat. 
D ESC RIFTIO N 

The portable pixmap format isa lowest common denomi nator color image file format. The definition isasfollows: 

A "magic number" for identifying the file type. A ppm fi le's magic number isthetwo characters P3. 

Whitespace(blanks, Tabs, CRs, LFs). 

A width, formatted asASCII charactersin decimai. 

Whitespace. 

A height, again in ASCII decimai. 
Whitespace. 

The maximum color-component value, again in ASCII decimai. 
Whitespace. 

Width * height pixels, each three ASC 1 1 decimai values between 0 and thespecified maximum value, starti ngat the top-left 
corner of the pixmap, proceeding in normal English reading order. The three values for each pixel represent red, green, and 
blue; a value of 0 meansthat color isoff, and the maximum value meansthat color ismaxed out. 
Characters from a#tothenextend-of-lineareignored (comments). 
No line should belonger than 70 characters. 

H ere i san exampleof asmall pixmap in this format: 

P3 

# feep.ppm 

4 4 

15 

000000000 15 0 15 
0000 15 7000000 
0000000 15 7000 
15 0 150 0 0 00 0 0 0 0 



Programs that read this format should beaslenient as possi ble, accepting anythingthat looks remotely like a pixmap. 
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Thereisalso a varianton the format, availableby setti ng the rawbits option at compi le ti me. Thisvariant isdifferent in the 
followingways 

The"magic number" is P6 instead of P3. 

The pixel valuesarestored asplain bytes, instead of ASCII decimai. 

Whitespaceisnot allowed in thepixelsarea, and only a single character of whitespace (typi cally a newline) isallowed after 
themaxval. 

T hefiles are smaller and manytimesfasterto read andwrite. 

N otethat this raw format can only beused for maxvals lessthan or equal to 255. If you usetheppm library and try to writea 
filewith a larger maxval, it will automati cally fall back on theslower but more general plain format. 

SEEALSO 

giftoppm(l), gouldtoppm(l), ilbmtoppm(l), imgtoppm(l), mtvtoppm(l), pcxtoppm(l), pgmtoppm(l), piltoppm(l), picttoppm(l), 
pjtoppm(l), qrttoppm(l), rawtoppm(l), rgb3toppm(l), sldtoppm(l), spctoppm(l), sputoppm(l), tgatoppm(l), ximtoppm(l), 
xpmtoppm(l), yuvtoppm(l), ppmtoacad(l), ppmtogif (1), ppmtoicr(l), ppmtoilbm(l), ppmtopcx(l), ppmtopgm(l), ppmtopil(l), 
ppmtopict(l), ppmtopj(l), ppmtopuzz(l), ppmtorgb3(l), ppmtosìxel(l), ppmtotga(l), ppmtouil(l), ppmtoxpm(l), ppmtoyuv(l), 
ppmdither(l), ppmforge(l), ppmhist(l), ppmmake(l), ppmpat(l), ppmquant(l), ppmquantall(l), ppmrelief (1), pnm(5), pgm(5), pbm(5) 

AUTHOR 

Copyright 1989, 1991 byjef Poskanzer. 

27 September 1991 



/proc 

/proc— Process information pseudo-fi lesystem. 
D ESC RIPTIO N 

/proc is a pseudo-fi lesystem that isused asan interface to kernel data structures rather than reading and interpreting /dev/ 
kmem. M ostof it isread-only, but somefilesallow kernel variablesto bechanged. 

Thefollowing outlinegivesaquick tour through the /proc hierarchy. 

[number ] There is a numeri cai subdirectory for each running process; the subdirectory isnamed by the 

processID . Each containsthefollowing pseudo-fi les and directories. 

cmdiine T his holds the complete command li ne for the process, unlessthewholeprocesshasbeen swapped 

out or unless the process is a zombie. In either of theselater cases, there isnothing in this fi le: That 
is, a read on thisfilewill return as having read 0 characters. Thisfile isnull-terminated but not 
newline- terminat ed. 

cwd This is a link current working directory of the process. To find outthecwd of process 20, for 

instance, you can do this: ed /proc/20/cwd; /bin/pwd. N otethat the pwd command isoften ashell 

built in and might notwork properly in thiscontext. 
environ T his file contains the environment for the process. The entries are separated by nuli characters, and 

there may bea nuli character at the end. Thus, to print out the environment of processi, you 

would do 

(cat /proc/1 /environ; echo) ] tr "\000" "\n" 

For a reason why one should want to do this, see nio(8). 
exe A pointer to the binary that wasexecuted and appearsasasymbolic link. readiink(2) on theexe 

special file returns a string in the format: 

[devi ce ] :i n o d e 

For example, [0301 ] : 1502 is inode 1502 on device major 03 (ID E, M FM , and so on drives), minor 




01 (first partition on the first drive). Also, the symbolic link can bedereferenced normally; 
attemptingto open exe will open theexecutable You can even type/proc/[number ]/exe to run 
anothercopy of thesameprocessas [number ]. 
find(l) with the -inum option can beused to locate thefile 
fd This isa subdirectory contai ni ngone entry foreach fi lethat the process has open, named by itsfile 

descriptor, and that isa symbolic link to theactual file (as the exe entry does). Thus, 0 is standard 
input, 1 standard output, 2 standard error, and so on. 

Programs that will takeafilenamebut will nottake the standard input and thatwriteto afilebut 
will not send their output to standard output can beeffectively foiled thisway, assumi ng that -i is 
theflag designating an input fileand -o istheflag designati ng an output file: 

foobar -ì /proc/self /f d/0 -o /proc/self /fd/1 ... 

and you have a working filter. N otethat this will not work for programs that seek on their files 
becausethefiles in thetd directory are not seekable. 

/proc/seif/fd/N is approxi mately the same as /dev/fd/N in sorneU N IX and U N IX-like system s. 
M ost Linux makedev seri pts symboli cai ly I i nk /dev/fd to /proc/seif/fd, in fact. 
maps A fi le contai ni ng thecurrently mapped memory regionsand their access permissions. 

Theformat is 



a d d r e s s 


per ms 


offset 


de\i 


node 


00000000 -0002f 000 


r-x- 


00000400 


03:03 


1401 


0002f 000 -00032000 


rwx-p 


0002f400 


03:03 


1401 


00032000 -0005b000 


rwx-p 


00000000 


00:00 


0 


60000000-60098000 


rwx-p 


00000400 


03:03 


215 


60098000 -600C7000 


rwx-p 


00000000 


00:00 


0 


bfffa000-c0000000 


rwx-p 


00000000 


00:00 


0 



address isthe address space in the process that it occupies. per ms isa set of permissions: r =read, w 
= write, x =execute, s =shared, p = private (copy on write). 

offset isthe offset into the fiie/wh at ever , dev is the device (major: minor), and i node istheinode 
on that device. 0 indicatesthat no inodeis associ ated with the memory region, as the case would be 
with bss. 

mem This is not the same as the mem (1,1) device, despite the fact that it has the same device numbers. 

The /dev/mem device is the physical memory beforeany address translati on isdone, but themem file 
here isthe memory of the process that accessesit. This cannot bemmap(2)ed currently, and will not 
beuntil a general mmap(2) isaddedto the kernel. (Thismight havehappened bythetimeyou read 
this) 

mmap D irectory of maps by mmap(2) that are symbolic links such asexe, fd/*, and so on. N otethat maps 

includes a superset of this information, so /proc/*/mmap should beconsidered obsolete. 
0 isusually iibc.so.4. 

/proc/*/mmap was removed in Linux kernel version 1.1.40. (It reallywas obsolete!) 
root UNIX and Linux support the idea of a per-process root of thefilesystem, set by thechroot(2) 

system cali, root pointsto thefilesystem root and behavesasexe, fd/*, and so on do. 
stat Status information about the process. This isused by ps(l). Thefields, in order, with their proper 

scanf(3) format speci fi ers, are 

pid %d The process ID . 

comm %s Thefilenameof theexecutable in parentheses. This is visible whether or not 

theexecutableisswapped out. 
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state %c 



ppid %d 
pgrp %d 
session % 
tty %d 
tpgid %d 

flags %u 



minflt %u 

cminflt %u 
majflt %u 

cmajflt %u 
utime %d 
stime %d 
cutime %d 

cstìme %d 

counter %d 

priority %d 

timeout %u 
itrealvalue %u 

starttime %d 
vsize %u 
rss %u 



rlim %u 
startcode %u 
endcode %u 
startstack %u 
kstkesp %u 

kstkeip %u 
signal %d 
blocked %d 



Onecharacter from the stri ng rsdzt whereR isrunning, s is sleeping in an 

interruptible wait, d issleeping in an uninterruptible wait or swapping, z is 

zombie, and t istraced orstopped (on a signal). 

The PI D oftheparent. 

Theprocessgroup ID of the process. 

ThesessionlD of theprocess. 

T he tty the process uses. 

The process group I D of the process that currently owns the tty that the 
process is con nected to. 

The flags of theprocess. Currently, everyflag hasthemath bit set because 
crt0.s checksfor math emulation, so thisisnot included in the output. This 
isprobably a bug because not every process is a compiled C program. The 
math bitshould beadecimal 4, and thetraced bit is deci mal 10. 
Thenumber of mi norfaults the process hasmade, thosethat havenot 
required loading a memory page from disk. 

The numberof minor faults that the process and itschildren havemade. 
Thenumber of major faults the process hasmade, thosethat have required 
loadi ng a memory page from disk. 

Thenumber of major faults that the process and itschildren havemade. 
Thenumber of jiffies that this process hasbeen scheduled in user mode. 
T he numberof jiffies that this process hasbeen scheduled in kernel mode. 
Thenumber of jiffies that this process and itschildren havebeen scheduled 
in user mode 

The numberof jiffies that thisprocess and itschildren havebeen scheduled 
in kernel mode. 

Thecurrent maximum size in jiffies of theprocess's next timeslice, or what is 
currently left of its current timeslice if it is the currently running process. 
The standard nicevalue plus fifteen. The valueisnever negative in the 
kernel. 

T he ti me i n j iffies of the process's next ti me-out. 

The ti me (in jiffies) before the next sigalrm issentto the process due to an 

interval timer. 

Timethe process started in jiffies after system boot. 
Virtual memory size. 

Resident set size Number of pages the process has in real memory, minus3 
for admi ni strati ve purposes. T his is just the pages that count toward text, 
data, or stack space. This does not include pages that have not been demand- 
loaded in or that areswapped out. 

Current limit in byteson therss of theprocess(usually2,i47,483,647). 
Theaddressabovewhich program textcan run. 
Theaddress below which program text can run. 
The address of the start of the stack. 

Thecurrent valueof esp (32-bit stack pointer), asfound in the kernel stack 
page for the process. 

Thecurrent eip (32-bit instruction pointer). 
Thebitmap of pendi ng signals (usuai ly 0). 
Thebitmap of blocked signals (usually 0, 2 for shells). 




sigignore %d T he bitmap of ignored signals. 

sigcatch %d Thebitmap of catched signals. 

wchan %u This is the "channel" inwhich theprocessiswaiting. Thisistheaddressof a 

system cali and can belooked up in a name list if you need atextual name. (If 
you havean up-to-date /etc/psdatabase, then try ps -1 to seethewcHAN field 
in action.) 

T his is a col lection of CPU and system architecturedependent items; foreach supported architec- 
tureisadifferent list. Theonlytwo common entri es are cpu, which istheCPU currently in use, 
and BogoMiPs, a system Constant that iscalculated during kernel initialization. 
Text li sci ng of major numbersand devi ce groups. This can beused by makedev seri ptsfor consis- 
tency with the kernel. 

T his is a list of the regi stered ISA DMA (direct memory access) channelsin use. 

A text listi ngof the fi lesystems that were compi led into the kernel. Incidentali, thisisused by 

mount(l) to cyclethrough differentfilesystemswhen none is specified. 

Thisisused to record the number of interrupts per each IRQ on (at least) the Ì386 architecture. 

Very easy to read formattingdone in ASCII. 

This is a list of currently regi stered input-output port regionsthat are in use 

Thisfilerepresentsthephysical memory of the system and isstored in the core fi le format. With 

thispseudo-fileand an unstripped kernel (/usr/src/iinux/toois/zsystem) binary, gdb can beused 

to examinethecurrent state ofany kernel data structures. 

Thetotal length of thefileisthesizeof physical memory (RAM ) plus4KB. 

This file can beused instead of thesysiog(2) system cali to log kernel messages. A processmust 

havesuperuser privilegesto read this file, and only oneprocessshould read thisfile. T his fi le should 

notberead if a sysiog processisrunning that uses the sysiog(2) system cali facilityto log kernel 

messages. 

Information in thisfile is retri eved with thedmesg(8) program. 

This holds the kernel exported symbol definitions used by themoduies(X) toolsto dynamically link 
and bind loadablemodules. 

Theload average numbersgive the number ofjobs in therun queueaveraged over 1, 5, and 15 

minutes. They are the sameas theload average numbers given by uptime(l) and other programs. 

Thisfile is only present if configdebugmalloc was defined during compilation. 

Thisisused by free(l) to report theamount of freeand used memory (both physical and swap) on 

thesystem aswell astheshared memory and buffersused by the kernel. 

It is in the same format astree(l) except in bytesratherthan KB. 

A text list of the modules that havebeen loaded by thesystem. 

Variousnet pseudo-files, ali of which give the status of some partof the networking layer. These 
fi les contai n ASCII structures and are thereforereadable with cat. H owever, the standard 
netstat(8) suite provides much ci eaner access to these fi les. 

This holds an ASCII readabledump of the kernel ARP tableused for address resolutions. It will 
show both dynamically learned and pre-programmed ARP entri es. The format is 

IP address HW type Flags HW address 

10.11.100.129 0x1 0x6 00:20:8A:00:0C:5A 

10.11.100.5 0x1 0x2 00:C0:EA:00:00:4E 

44.131.10.6 0x3 0x2 GW4PTS 



ip address isthe ipv4 address of the machine. The hw type i s the hardware type of the address from 
RFC 826. The flags are the internai flags of the ARP structure(as defined in /usr/inciude/iinux/ 
if_arp.h) andtheHW address isthe physical layer mapping for that IP addressif it isknown. 



Thedev pseudo-fi le contai ns network devi ce status i nformation. Thisgives the number of received 
and sent packets, the number of errorsand colli sions, and other basic stati stics. Theseareused by 
theifconfig(8) program to report device status. The format is 

Inter-] Receive | Transmit 

face | packets errs drop fifo trame | packets errs drop tifo colls carrier 
lo: 0 0 8 8 0 2353 8 8 8 8 8 

eth8: 644324 18 8 1 563770 8 8 8 581 8 

N o i nformation. 
N o i nformation. 

This fi le uses the same format astheARP file and contai ns the current reverse mapping database 
used to provide rarp(8) reverse ad dress lookup servi ces. If rarp isnot confi gured into the kernel, 
thisfilewill not bepresent. 

H oldsadump of theRAW socket table. M uch of theinformation isnotof useapart from 
debugging. The si valueis the kernel hash slot for the socket; theiocai_address is the locai address 
and protocol number pair. st istheinternal status of the socket. Thetx_queue and rx_queue are the 
outgoingand incomingdata queuein termsof kernel memory usage. Thetr, tm->wnen, and rexmits 
fields are not used by RAW. Theuid field holds the creator euid of the socket. 
N o information but lookssimilarto route(8). 

This fi le holds the ASC II data needed for the IP, ICM P, TCP, and UD P management information 
basesforan snmp agent. Asof writing, theTCP mie isincomplete. It should becompleted by 1.2.0. 
Holdsadumpof theTCP socket table. M uch of theinformation isnotof useapart from 
debugging. The si valueis the kernel hash slot for the socket; theiocai_address is the locai address 
and port number pair. The remote_address is the remote address and port number pair (if 
connected). st istheinternal status of the socket. Thetx_queue and rx_queue aretheoutgoing and 
incomingdata queuein termsof kernel memory usage. Thetr, tm->wnen, and rexmits fieldshold 
internai information of the kernel socket state and areonly useful for debugging. Theuid field 
holds the creator euid of the socket. 

H oldsadump of theU D P socket table. M uch of theinformation isnotof useapart from 
debugging. The si valueis the kernel hash slot for the socket; theiocai_address is the locai address 
and port number pair. The remote_address is the remote address and port number pair (if 
connected). st istheinternal status of the socket. Thetxqueue and rx_queue aretheoutgoing and 
incomingdata queuein termsof kernel memory usage. Thetr, tm->when, and rexmits fields are not 
used by U DP. Theuid field holds the creator euid of the socket. The format is 

si local_address rem_address st tx_queue rx_queue tr rexmits tm->when uid 

1: 81642C89:0201 0C642C89:03FF 01 00000000:00000001 01: 000071 BA 00000000 0 

1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 
1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 

Liststhe UNIX domain sockets presentwithin the system and their status. The format is 

Num RefCount Protocol Flags Type St Path 

0: 00000002 00000000 00000000 0001 03 

1: 00000001 00000000 00010000 0001 01 /dev/printer 

Num isthe kernel table slot number, Retcount isthe number of usersof the socket, Protocol is 
currently always 0, and Fiags represents the internai kernel flags holding the status of the socket. 
Type is currently always 1 (UNIX domain datagram sockets are not yet supported in the kernel), st 
istheinternal state of the socket and Path isthe bound path (if any) of thesocket. 




Thisisa listingof ali PCI devicesfound during kernel initialization and their configuration. 
A directory with theSCSI mid-level pseudo-file and variousSC SI low-level driver di rectories, 
which contai n afilefor each SCSI host in this system, ali of which give the status of some part 
of the SC SI IO subsystem. These fi les contai n ASC II structures and are thereforereadable with 

cat. 

You can also writeto some of the fi lesto reconfi gure the subsystem or switch certain featureson 
or off. 

Thisisa listingof ali SCSI devicesknown to the kernel. The listi ng issimilarto theoneseen 
during bootup. scsi currently supportsonly the single devi ce command, which allows rootto 
add a hot-plugged devi ceto the list of known devices. 

An echo 'scsisingledevicel 0 5 0'> /proc/scsi/scsi WÌII Cause hOSt scsil tO SCan On SCSI 

channel 0 foradeviceon ID 5 LUN 0. If th ere i sai ready a devi ce known on this addressor the 
addressisinvalid, an errar will bereturned. 

drivername Can Currently beNCR53c7xx, aha152x, aha1542, aha1740, aic7xxx, buslogic, eata_dma, 
eata_pio, fdomain, in2000, pas16, qlogic, scsi_debug, seagate, t128, u15-24f, ultrastor, Or 

wd7000. These di rectories show up forali driversthat regi stered at least oneSCSI H BA. Every 
directory contai nsone fi le per regi stered host. Every host-file isnamed after the num ber the 
host got assigned during initialization. 

Reading these files will usually show driver and host configuration, statistica and so on. 
Writingto these fi les allows different thingson different hosts. For example, with theiatency 
and noiatency commands, rootean switch on and off command latency measurement code in 
theeata_dma driver. W ith theiockup and uniock commands, root can control bus lockups 
simulated by thescsi_debug driver. 

This directory refersto the process accessi ng the/proc filesystem and i s i denti cai to the /proc 
directory nam ed by the process I D of the sam e process. 

kernel/system Statisti CS. 

Thenumber of jiffies (1/lOOths of asecond) that the system spent in user mode, user mode 
with low priority (nice), system mode, and the i die task. Thelast valueshould belOO timesthe 
second entry in theuptime pseudo-file. 

Thefour disk entri es are not implemented at this ti me l'm not even surewhat this should be 
because kernel stati stics on other machines usually track both transfer rate and I/O s per second 
and thisonly allows for one fi eld per drive. 

Thenumber of pages the system paged in and thenumber that were paged out (from disk). 
Thenumber of swap pages that havebeen brought in and out. 
Thenumberof interrupts received from the system boot. 
The number of context switches that the system underwent. 
Boottimein secondssincetheepoch (January 1, 1970). 

This directory (present sirice 1.3.57) contai ns a number of files and subdi rectoriescorrespond- 
ing to kernel vari ables. These vari ables can beread and sometimes modified using theproc 
filesystem and using the syscti(2) system cali. Presently, there are subdi rectories kernel, net, 
and vi» that each contai n more fi les and subdi rectories. 

T his COntainS the files domainname, file-max, file-nr, hostname, inode-max, inode-nr, osrelease, 
ostype, panie, real-root-dev, securelevel, and version, with function fai ri y clear from the 

name 

The(read-only) file fiie-nr gives thenumberof fi les presently opened. Thefileme-max gives 
the maximum number of open fi les the kernel iswillingto handle. If 1024 isnot enough for 

yOU, try echo 4096 > /proc/sys/kernel/file-max. 

Similarly, the fi les inode-nr and inode-max indicate the present and the maximum number of 
inodes. 
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ThefileSostype, osrelease, and version give Substrings Of /proc/version. 

The fi le panie givesr/w access to the kernel variablepanic_timeout. If thisiszero, the kernel will 
loop on a panie; if nonzero, it indicatesthat the kernel should auto reboot after thisnumber of 
minutes. 

The file secureievei seems rather meaninglessat present; root isjusttoo powerful. 
uptime Thisfilecontainstwo numbers: theuptimeof the system (seconds) and theamount of ti me 

spentin idleprocess (seconds). 
version Thisstring identifies the kernel version that iscurrently running. For instance: 

Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 

SEEALSO 

cat(l), find(l), f ree(l), mount(l), ps(l), tr(l), uptime(l), readlink(2), mmap(2), chroot(2), syslog(2), hier(7), arp(8), 
dmesg(8), netstat(8), route(8), ifconfig(8), procinfo(8) and much more 

C0NF0RMST0 

Thisroughly conformsto a Linux 1.3.11 kernel. Please update thisas necessary! Last updated for Linux 1.3.11. 
CAVEATS 

Note that many stri ngs (the environment and command line) are in the internai format, with subfieldsterminated by nuli 
bytes, soyou mightfindthatthingsaremorereadableifyouuseod -cortr "\000" "\n" to read them. 

Thismanual page is incomplete, possi bly inaccurate, and isthekind of thing that needsto be updated very often. 
BUGS 

The /proc filesystem may introduce security holes into processes running with cnroot(2). For example, if /proc ismounted in 
theenroot hierarchy, acndir(2) to /proc/ 1 /root will return to the originai root of the filesystem. T hi s may beconsidered a 
featureinstead of a bug because Linux doesnotyet support thetchroot(2) cali. 

22 July 1996 



protocols 

protocois— T he protocols definition file. 
D ESC RIPTIO N 

T his fi le is a piai n ASCII file, descri bing the various D ARPA Internet protocols that areavailablefrom the TCP/IP 
subsystem. It should beconsulted instead of using the numbers in the ARPA include files or, even worse, just guessing them. 
These numbers will occur in the protocol field of any IP header. 

Keep thisfileuntouched because changeswould result in incorrect IP packages. Protocol numbers and namesarespecified by 
the D D N N etwork I nformation C enter. 

Each line isof thefollowing format: 

protocol nu mb e r a I i as es ... 

Thefieldsaredelimited by spacesortabs. Empty linesand li nes starti ng with a hash mark (#) areignored. Remainder of lines 
arealso ignored from theoccurrenceof a hash mark. 

Thefield descri ptionsare 

protocol Thenativenameforthe protocol— for example, ip, tep, orudp. 

number The officiai number for this protocol asitwill appearwithin thelP header. 

ai i ases Optional al iases for the protocol. 



rcsfile 



Thisfilemight be distri buted over a network usinga network-widenaming servi ce such asYellow Pages/N IS or BIN DI 
H oso d. 

FILES 

/etc/protocois T he protocols definition file. 

SEEALSO 

getprotoent(3), Guide toYellow P ages Servi ce, Guide to BIN D/H esiod Service 

Linux, 18 October 1995 



rcsfile 

restile— Format of RCS file. 
DESCRIVO N 

An RC S file's contents are described by thegrammar below. 

Thetext isfree format: space, backspace, tab, newline, vertical tab, form feed, and carri age return (col lectively, whitespace) 
haveno significance except in strings. H owever, whitespace cannot appear within an ID, num, or sym, and an RCS file must 
end with a newline. 

Strings are en ci osed by @. I f a stri ng containsa?, it must bedoubled; otherwise, strings can contain arbitrary binary data. 

The meta syntaxuses the following conventi ons: \ (bar) separates alternati ves; { and } enclose optional phrases. { and }* 
enclosephrasesthat can berepeated zero or moretimes. { and {+ enclose phrases that must appear at least once and can be 
repeated. Terminal symbolsarein boldface; non-terminal symbolsarein i tali cs 

rcstext : : = a d mi n {delta}* desc {deltatext}* 
a d mi n : := head {num}; 

{ b r a ne h {num}; } 
access {id}*; 
symbol s {sym : num}*; 
oc ks {i d : num}*; {stri et ; } 

{ comment {st r i ng }; } 

{ expand {stri n g > ; } 

{ newpb r a s e }* 
delta : := num 

dat e num; 

a u t hor i d ; 

state {i d }; 

branches {num}*; 

next {rum}; 

{ new-phrase }* 
desc : := desc stri n g 
del t at ext : := num 

log stri n g 
{ n e wp hr as e }* 
t ext s t r i n g 
num : : = {d i g i t ] . }+ 

digit : := 0 j 1 j 2 j 3 | 4 | 5 | 6 | 7 8 j 9 
i d : := {num} i debar {i dchar ] num}* 
sym : := {di gì t }* i dchar {i dchar ] digit }* 
dchar ::= any visible graphic character except special 
speci al ::=$], . j : | ; ] @ 
string ::= @{any character, with @doubled}*@ 
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newphrase :: 
wor d : := i d 



i d wor d * ; 
num ! stri n g 



Identifiers are case sensitive. Keywordsarein lowercaseonly. Thesetsof keywords and i denti fi erscan overlap. In most 
environments, RCS uses the ISO 8859/1 encoding: visiblegraphic characters are codes 041- 176 and 240-377, and 
whitespacecharactersarecodesOlO-015 and 040. 

Dates, which appear after the date keyword, areof theform Y.mm.dd.hh.mm.ss, whereY istheyear, mm themonth (01-12), 
dd the day (01-31), hh the hour (00-23), mm the minute (00-59), and ssthesecond (00-60). Y contains just the lasttwo 
digitsof theyearforyearsfrom 1900 through 1999, and ali thedigitsof yearsthereafter. Dates use the Gregorian calendar; 
timesuseUTC. 

The newphrase productions i n the grammar are reserved for future extensionsto the format of RCSfiles. No newphrase will 
begin with any keyword al ready in use. 

The deità nodesform atree. AH nodeswhosenumbersconsist of a single pai r (such as2.3, 2.1, 1.3, and so on) areon the 
trunk and arelinked through thenextfield in order of decreasi ng numbers. The head fidd in theadmìn nodepointsto the 
head of that sequence (contai ns the highest pair). Thebranch nodein theadmìn nodeindicates the default branch (or 
revision) for most RCS operations. If empty, the default branch is the highest branch on the trunk. 

AH delta nodeswhose numbers consist of 2n fields (n2) (such as 3.1.1.1, 2.1.2.2, and so on) arelinked asfollows. AH nodes 
whose first 2n-l number fields are i denti cai arelinked through thenext field in order of increasi ng numbers. For each such 
sequence, the delta node whose number isidentical to the first 2n-2 number fields of the deltason that sequence iscalled 
thebranchpoint. Thebranches field of a node contains a list of the numbers of the first nodes of ali sequences for which it is 
a branchpoi nt. This list is ordered in increasing numbers. 

Thefollowingdiagram showsan exampleof an RCSfile'sorganization. 

Head 
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r650l\/6r 1183 

IDENTIFICATION 

Author: Walter F. Tichy, Purdue University, West Lafayette, IN, 47907. M anual Page Revision: 5.6; ReleaseDate: 1995/ 
06/05. Copyright 1982, 1988, 1989, Walter F. Tichy. Copyright 1990, 1991, 1992, 1993, 1994, 1995, Paul Eggert. 

SEEALSO 

rcsintro(l), ci(l), co(l), ident(l), rcs(l), rcsclean(l), rcsdiff(l), rcsmerge(l), rlog(l), W alter F. Tichy, RCS, "A System 

for Version Control," Software- Practice & Experience, 15, 7 (July 1985), 637-654. 

GNU,5Junel995 



resolver 

resolver— Resolver configuration file. 
SYNOPSIS 

/etc/resolv.conf 

DESCRIVO N 

The resolver is a set of routines in the C library (resoiv(3)) that provi des access to the Internet Domain N ame System. The 
resolver configuration fi le contai ns informati on that isread by the resolver routines thefirst timethey areinvoked by a 
process. Thefileisdesigned to be human readableand contai ns a list of keywordswith valuesthat provi de vari oustypesof 
resolver information. 

On a normally configured system, thi s fi le should not benecessary. Theonly nameserver to bequeried will beon the locai 
machine, the domain nameis determi ned from thehost name, and the domain search path isconstructed from the domain 
name 

Thedifferent configuration optionsare 

nameserver Internet address (in dot notati on) of a nameserver that the resolver should query. U p to 

maxns (currently 3) nameservers may belisted, one per keyword. Ifthere are multiple servers, 
the resolver library queriesthem in theorder listed. If no nameserver entri es are present, the 
default isto use the nameserver on the locai machine. (Thealgorithm used isto try a 
nameserver, and if the query times out, try the next until you run out of nameservers, and 
then repeattryingall the nameservers until a maximum number of retri es arem ade) 

domain Locai domain name. M ost queriesfor nameswithin thisdomain can use short names 

relative to the locai domain. If no domain entry is present, thedomain isdetermined from 
thelocal hostnamereturned by gethostname(2); thedomain partistaken to beeverything 
after thefirst .. Finally, if thehostnamedoesnot contain adomain part, the root domain is 
assumed. 

search Search list for hostnamelookup. The search list is normally determi ned from thelocal 

domain name; by default, itcontainsonly the locai domain name This may bechanged by 
listing thedesi red domain search path following the search keyword with spacesortabs 
separating the names. M ost resolver queries will beattempted usingeach component of the 
search path in turn until a match isfound. N otethat this process may beslow and will 
generate a lot of network traffic if the servers for the listed domai ns are not locai and that 
queries will timeout if no server is avai lable for oneof thedomains 
Thesearch list is currently limited to sixdomainswith a total of 256 characters. 

sortiist sortiist allows addresses returned by getnostbyname to be sorted. A sort list is specified by 

IP address netmask pairs. Thenetmask is optional and defaultsto the naturai netmask of 
the net. The IP address and optional network pairs are separated by slashes. Upto 10 pairs 
may be specified. 

sortlist 130.155.160.0/255.255.240.0 130.155.0.0 
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options options allows certain internai resolver variablesto bemodified. Thesyntax is 

options opti o n ... 

whereoption isoneof thefollowing: 

debug SetS RESDEBUG in res. options. 

ndotsm sets a threshold for thenumber of dotsthat must appear in a namegiven to 
res_query (see resoiver(3)) beforean initial absolute query will bemade. The default for n is 
1, meaningthat if thereareany dotsin a name, the name will betried first asan absolute 
namebeforeany search list elements areappended to it. 

The domain and search keywords are mutually exclusive. If morethan oneinstanceof thesekeywordsispresent, thelast 
instancewins. 

The search keyword of a system 's resoiv.cont filecan beoverridden on a per- process basi sby setti ng the environment 
variable localdomain to a space-separated list of search domai ns. 

The options keyword of asystem's resoiv.cont filecan beamended on a per-process basisby setti ng the environment 
variable res_options to a space-separated list of resolver options asexplained previously. 

The keyword and valuemust appear on a single line, and the keyword (such asnameserver) must start the line The value 
follows the keyword, separated by whitespace 

FILES 

/etc/resolv.conf 

SEEALSO 

gethostbyname(3), resoiver(3), hostname(7), named(8), N ame Server 0 perations G uide for BIN D 

11 Novemberl993 

securetty 

securetty— File that liststtys from which rootcan log in. 
D ESC RIPTIO N 

/etc/securetty isused by ìogin(l); the file contains the device names of tty lines {one per line, without leading /dev/) on 
which root isallowed to log in. 

FILES 

/etc/securetty 

SEEALSO 

login(l) 

Linux, 29 December 1992 

services 

services— Internet network serviceslist. 
DESCRIPTION 

services isa piai n ASC II file providing a mapping between friendly textual names for Internet services and their underlying 
assigned port numbersand protocol types. Every networking program should look into thisfileto get theport number (and 
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protocol) for itS servi ce. The C library rOUtine3getservent(3), getservbyname(3), getservbyport(3), setservent(3), and 

endservent(3) support querying thisfilefrom programs. 

Port numbers are assi gned by thelAN A (Internet Assi gned N umbersAuthority), and their current policy isto assign both 
TCP and U D P protocolswhen assigning a port number. Therefore, most entries wi II havetwo entri es, even forTCP-only 
services. 

Port numbers below 1024 (so-called low-numbered ports) can only bebound to by root (seebind(2), tcp(7), and udp(7).) 
Thisisso that clients connecting to low-numbered ports can trust that theservicerunningon the port isthe standard 
implementation and not a rogueservicerun by a user of the machine. Well-known port numbers specified by thelAN A are 
normally located in thisroot-only space 

Thepresenceof an entry for a servi ce in the services filedoes not necessari ly mean that the servi ce iscurrently running on 
the machine. Seeinetd.conf(5) for the configurati on of Internet services offered. N otethat notali networking services are 
started by inetd(8) and so won't appear in inetd.conf(5). In parti cular, news (N NT P) and mail (SM TP) servers are often 
initialized from the system boot scripts. 

The location Of the services file isdefi ned by PATH SERVICES in /usr/include/netdb.h. ThisiSUSUally setto /etc/services. 

Each linedescribesoneserviceand isof theform: 

servi ce- name port /protocol [ali ases . . . ] 

servi ce - na me The friendly nametheserviceisknown by and looked up under. It is case sensi ti ve. Often, 

the client program isnamed after the s e r v ce - nane, 
port The port number (in decimai) to use for this servi ce. 

protocol Thetypeof protocol to beused. Thisfidd should match an entry in theprotocois(5) file. 

Typical valuesincludetcp and udp. 
ai i ases An optional space- ortab-separated list of other names for this service(see the Bugssection 

below). Again, the names are case sensitive. 

Either spacesortabs may beused to separate the fi elds. 

Comments are started by thehash sign (#) and conti nueuntil the end of theline Blank lines are skipped. 

T he s e r v ce - nane should begin in the first column of the file becauseleadingspaces are not stripped. servi ce - names can be 
any printable characters excluding space and tab; however, a conservative choiceof characters should beused to minimize 
inter-operability problems. For example, a-z, 0-9, and hyphen (-) would seem a sensi ble choice. 

Lines not matching this format should not bepresent in the fi le (Currently, they are si lently skipped by getservent(3), 
getservbyname(3), and getservbyport(3). H owever, this behavior should not be relied on.) 

As a backwards compati bilityfeature, the slash (/) between the port number and protocol name can in fact be either a slash 
oracomma(,). Useof the comma in modem installations is depreciated. 

Thisfilemight be distri buted over a network usinga network-widenaming servi ce such asYellow Pages/N IS or BIN DI 
H esiod. 

A sample services filemight look likethis: 



netstat 


15/tcp 




qotd 


17/tcp 


quote 


msp 


18/tcp 


# message send protocol 


msp 


18/udp 


# message send protocol 


chargen 


19/tcp 


ttytst source 


chargen 


19/udp 


ttytst source 


ftp 


21 /tcp 




It 


22 - unassigned 


telnet 


23/tcp 
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BUGS 

There is a maximum of 35 aliases, dueto theway thegetservent(3) code iswritten. 

Lines longerthan bufsiz (currently 1024) characters will beignored by getservent(3), getservbyname(3), and 
getservbyport(3). H owever, thiswill also cause the next lineto bemisparsed. 

FILES 

/etc/services The Internet network servi ces I i st 

/usr/include/netdb.h D efi ni ti On Of _PATH_SERVICES 

SEE ALSO 

getservent(3), getservbyname(3), getservbyport(3), setservent(3), endservent(3), protocols(5), listen(2), inetd . conf (5), 

inetd(8), Assigned NumbersRFC, most recently RFC 1700 (AKA STD0002),GuidetoYellow Pages Service, Guide to 
Bl N D/H eaod Service. 

Linux, 11 J anuary 1996 

shells 

sheiis— Pathnamesof valid login shells. 
DESCRIPTION 

/etc/sheiis is a text file that contai ns the full pathnamesof valid login shells. Thisfile isconsulted bychsh(l) and isavailable 
to bequeried by other programs. 

EXAMPLES 

/etc/sheiis may contain thefollowing paths: 

/bin/sh 
/bin/csh 

FILES 

/etc/shells 

SEE ALSO 

ohsh(l) 

21 Novemberl993 



syslog.conf 

sysiog.conf— sysiogd(8) configuration file. 



DESCRIPTION 

The sysiog.conf f i I e i s the confi guration fileforthesysiogd(8) program. It consistsof lineswith two fields: theseiector 
field, which specifies the types of messagesand prioritiesto which thelineapplies, and an action field, which specifiesthe 
action to betaken if a message sysiogd received matchestheselection criteri a. There cannot beany spacesin the action field. 
Theseiector field isseparated from the action field by oneor moretab or space characters (Thisisadeparturefrom the 
standard BSD way of doingthings; both tabsand spacescan beused to separate theseiector from the action.) 

Theseiector functions are encoded asafacility, a period (.), and a levd, with no intervening whitespace. Both the faci lity 
andthelevel are case insensitive. 



syslog.conf 



Thetaciiity describesthe part of the system generati ng the message and isoneof thefollowing keywords: auth, authpriv, 

cron, daemon, kern, lpr, mail, mark, news, syslog, user, uucp, and localo through local7. T hese keywords (with theexception 

of mark) correspond to the siimi larDv log_ valuesspecified to theopeniog(3) and sysiog(3) library routines. 

Theievei descri bes the severity of the message and isa keyword, optionally preceded by an equals (=), from thefollowing 
ordered list (higher to lower): emerg, aiert, cnt, err, warning, notice, info, and debug. T hese keywords correspond to the 
similarDv log_ valuesspecified to the sysiog library routine. 

Seesysiog(3) for further descri ptionsof both thetaciiity and ìevei keywords and their significance. 

If areceived message matches the specified facility and isof the specified level (or a higher level if level wasspecified without 
=), theaction specified in the action field will betaken. 

M ulti pie sei ectors may be specified for a single action by separati ng them with semicolon (;) characters. It isimportantto 
note however, that each selector can modify theones preceding it. 

M ulti pie faci I iti es may be specified for a single level by separati ng them with comma (,) characters. 
An asterisk (*) can beused to specify al I faci I iti es or ali level s. 

The special facility "mark" receives a message at priority "info" every 20 minutes(seesysiogd(8)). Thisisnot enabled by a 
facility field containingan asterisk. 

T he special level "none" disables a particular facility. 

Theaction field of each line specifies the action to betaken when theseiector field selects a message. Therearefourforms: 

A pattinarne (beginning with a leadingslash). Selected messagesareappended to the fi le. 

A hostname (preceded by an at (?) sign). Selected messagesareforwarded to thesysiogd program on thenamed host. 

A comma-separated list of users. Selected messagesarewritten to thoseusersif they arelogged in. 

An asterisk. Selected messagesarewritten to ali logged-in users. 

Blank linesand lineswhose first non-blank character isa hash (#) character areignored. 

EXAMPLES 

A configuration filemightappearasfollows: 

# Log ali kernel messages, authentication messages of 

# level notice or higher and anything of level err or 

# higher to the console. 

# Don't log private authentication messages! 

*. err; kern.*; auth. notice; authpriv. none /dev/ console 

# Log anything (except mail) of level info or higher. 

# Don't log private authentication messages! 

* .info; mail. none; authpriv .none /var/log/messages 

# Log debug messages only 

*.=debug /var/log/debug 

# The authpriv file has restricted access. 

authpriv.* /var/log/secure 

# Log ali the mail messages in one place. 

mail.* /var/log/maillog 

# Everybody gets emergency messages, plus log them on another 

# machine. 

*. emerg * 

*. emerg @arpa . berkeley . edu 
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# Root and Eric get alert and higher messages. 

*.alert root.eric 

# Save mail and news errors of level err and higher in a 

# special file. 

uucp.news.crit /var/log/spoolerr 

FILES 

/etc/sysiog.conf T he sysiogd(8) conf i gurati on file. 

BUGS 

Theeffectsof multi pie sei ectors are sometimes not intuitive For examplemaii.crit,*.err will select mail faci li ty messages at 
the level of err or higher, not at the level of crit or higher. 

SEEALSO 

syslog(3), syslogd(8) 

10 Mayl991 



termcap 

termcap— Terminal capability database. 
D ESC RIPTIO N 

Thetermcap database is an obsolete facility for describing the capabi lities of character-cell terminalsand printers. It is 
retai ned only for capability with old programs; new onesshould usetheterminfo(5) database and associ ated libraries. 

/etc/ termcap is an ASCII file (the database master) that lists the capabilities of many different typesof termi nals. Programs 
can read termcap to find the particular escape codes needed to control the visual attributes of the terminal actually in use. 
(Other aspectsof the terminal arehandled by stty.) Thetermcap database isindexed on the term environment variable. 

termcap entries must bedefined on a single logicai line, with \ used to suppressthenewline. Fields are separateci by :. The 
first field of each entry startsat the left-h and margin and containsa list of names for the terminal, separated by |. 

Thefirst subfield may(in BSD termcap entries from versions4.3 and prior) contain ashortnameconsistingof two 
characters. This short namemay consist of capital or small letters. In 4.4 BSD termcap entries, this field isomitted. 

Thesecond subfield (first in thenewer 4.4 BSD format) contai ns the name used by the environment variable term. It should 
bespelled in lowercase letters. Selectable hardware capabilities should bemarked by appendi ng a hyphen and asuffixto this 
name. U sual suffixes are w (more than 80 characters wide), am (automatic margins), nam (no automati c margins) and rv 
(reverse video display). The third subfield containsa long and descriptive name for this termcap entry. 

Subsequent fields contain the terminal capabilities; any conti nued capability linesmust beindented onetab from theleft 
margin. 

Although thereis no defined order, it issuggested to write first Boolean, then numeri c, and at last stri ng capabilities, each 
sorted alphabetically without looking at lower or upper speli ing. Capabilitiesof similarfunctionscan bewritten in oneline. 

Example: 

Head line: vt | vt1 01 | DEC VT 101 terminal in 80 character mode:\ 

Head line: Vt|vt101 -w|DEC VT 101 terminal in (Wide) 132 character mode:\ 

Boolean: :bs:\ 

Numeric: :co#80:\ 

String: :sr=nE[H:\ 



Boolean C apabi Mties 



5i 


Printer will notecho on screen 


am 


Automatic marginswhich meansautomatic linewrap 


bs 


Ctrl-HH (8 dee.) performsa backspace 


bw 


Backspaceon left margin wrapsto previous line and right margin 


da 


D i splay retai ned above screen 


db 


D i splay retai ned below screen 


eo 


A space erases ali characters at cursor position 


es 


Escape sequences and special characters work in status line 


gn 


G eneri c device 


he 


This is a hardcopy terminal 


HC 


Thecursor ishard to seewhen not on bottom line 


bs 


Has a status li ne 


bz 


H azeltinebug; theterminal cannot print tilde characters 


ib 


Terminal inserts nulls, not spaces, to fili whitespace 


km 


Terminal has a meta key 


mi 


Cursor movement works in insert mode 


ms 


C ursor movement works in standout/underline mode 


NP 


N o pad character 


NR 


ti does not reverse te 


nx 


N o paddi ng; must useXO N /XO FF 


OS 


Terminal can overstrike 


ul 


Terminal underlines, although it cannot overstrike 


xb 


Beehiveglitch; FI sends Escape and F2 sends "C 


Xb 


N ewline/wraparound glitch 


xo 


Terminal usesXON/XOFF protocol 


xs 


Texttyped over standouttext will bedisplayed in standout 


xt 


Teleray glitch; destructivetabsand odd standout mode 


N umeric Capabilities 


co 


Number of columns 


dB 


Delay in millisecondsfor backspaceon hardcopy termi nals 


dC 


Delay in millisecondsfor carri age return on hardcopy terminals 


dF 


Delay in millisecondsforform feed on hardcopy terminals 


dN 


Delay in millisecondsfor newlineon hardcopy terminals 


dT 


Delay in millisecondsfor tabulator stop on hardcopy terminals 


dV 


Delay in millisecondsfor verti cai tabulator stop on hardcopy terminals 


it 


D ifference between tab positions 


lb 


Heightof soft label s 


lm 


Linesof memory 


lw 


Width of soft label s 
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NumericCapabilities 



li 


N umber of lines 


NI 


Number of soft labels 


pb 


Lowest baud ratethat needs padding 


sg 


Standout glitch 


ug 


U nderline glitch 


vt 


Virtual terminal number 


WS 


Width of status li nei f di fferentfrom screen width 


String C apabi lities 


!1 


Shifted save key 


!2 


Shifted suspend key 


!3 


Shifted undo key 


#1 


Shifted help key 


#2 


Shifted home key 


#3 


Shifted input key 


#4 


Shifted cursor left key 


%0 


Redo key 


%1 


H elp key 


%2 


M ark key 


%3 


M essage key 


%4 


M ove key 


%5 


N ext-object key 


%6 


Open key 


%7 


Optionskey 


%8 


Previ ous-object key 


%9 


Print key 


%a 


Shifted messagekey 


%b 


Shifted move key 


%c 


Shifted next key 


%d 


Shifted options key 


%e 


Shifted previouskey 


%f 


Shifted print key 


*g 


Shifted redo key 


%h 


Shifted replace key 


%i 


Shifted cursor right key 


*i 


Shifted resumé key 


&a 


Shifted canee! key 


&1 


Reference key 


&2 


Refresh key 


&3 


Replace key 


&4 


Restart key 
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&5 


Resumé key 


&6 


Save key 


&7 


Suspend key 


&8 


U ndo key 


&9 


Shifted begin key 


*0 


Shifted find key 


*1 


Shifted command key 


*2 


Shifted copy key 


*3 


Shifted create key 


*4 


Shifted delete character 


*5 


Shifted delete line 


*6 


Select key 


*7 


Shifted end key 


*8 


Shifted clear line key 


*9 


Shifted exit key 


@0 


Find key 


91 


Begin key 


92 


C ancel key 


93 


Closekey 


@4 


Command key 


95 


Copy key 


@6 


C reate key 


@7 


End key 


98 


Enter/send key 


@9 


Exit key 


al 


I nsert one li ne 


AL 


Insert %1 lines 


ac 


Pai rs of block graphic characters to map alternate character set 


ae 


End alternative character set 


as 


Start alternative character set for block graphic characters 


bc 


Backspaceif not "H 


bl 


Audio beli 


bt 


M oveto previ oustab stop 


cb 


Clear from beginning of lineto cursor 


ce 


D ummy command character 


ed 


Clear to end of screen 


ce 


Clear to end of line 


cb 


M ove cursor horizontally only to column %i 


ci 


C lear screen and cursor home 


cm 


Cursor moveto row %1 and column %2 (on screen) 


CM 


M ove cursor to row %i and column %2 (in memory) 



continue? 
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String C apabilities 



cr C arri age return 

cs Serali region from line %1 to %2 

et Cleartabs 

cv M ove cursor verti cally onlyto line %1 

de D elete onecharacter 

dc D elete %i characters 

di D elete one line 

dl D elete %1 lines 

dm Begin delete mode 

do Cursor down one line 

do Cursor down #1 lines 

ds D i sable status I i ne 

eA E nable alternate character set 

ec E rase %1 characters starti ngat cursor 

ed End delete mode 

ei End insert mode 

ft Formfeed character on hardcopyterminals 

ts Return character to itsposition beforegoingto status line 

fi Thestringsent byfunction key fll 

F2 Thestringsent byfunction key fl2 

F3 Thestringsent byfunction key fl3 

F9 Thestringsent byfunction key fl9 

fa Thestringsent byfunction key f20 

fb Thestringsent byfunction key f21 

fz Thestringsent byfunction key f45 

Fa Thestringsent byfunction key f46 

Fb Thestringsent byfunction key f47 

Fr Thestringsent byfunction key f63 

hd M ove cursor a half li ne down 

ho Cursor home 

hu M ove cursor a half line up 

ii Initialization stringi atlogin 

i3 Initialization string 3 atlogin 

is Initialization string 2 atlogin 

ic Insert onecharacter 

ic Insert %1 characters 

it Initialization file 

im Begin insert mode 
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String C apabilities 



ip 


Insert pad ti me and needed special characters after insert 


iP 


I n i ti al i zati on program 


K1 


U pper-left key on keypad 


K2 


Center key on keypad 


K3 


U pper-right key on keypad 


K4 


Bottom-left key on keypad 


K5 


Bottom-right key on keypad 


k0 


Function key 0 


k1 


Function key 1 


k2 


Function key 2 


k3 


Function key 3 


k4 


Function key 4 


k5 


Function key 5 


k6 


Function key 6 


k7 


Function key 7 


k8 


Function key 8 


k9 


Function key 9 


k; 


Function key 10 


ka 


Clear ali tabs key 


kA 


Insert line key 


kb 


Backspace key 


kB 


Back tabstop 


kC 


Clear screen key 


kd 


Cursor down key 


kD 


Key for delete character under cursor 


ke 


Turn keypad off 


kE 


Key for clear to end of line 


kF 


Key for scrolli ng forward/down 


kh 


Cursor home key 


kH 


Cursor down key 


kl 


1 nsert character/ insert mode key 


kl 


Cursor left key 


kL 


Key for delete line 


kH 


Key for exit insert mode 


kN 


Key for next page 


kP 


Key for previous page 


kr 


Cursor rightkey 


kR 


Key for scrolli ng backward/up 


ks 


Turn keypad on 


kS 


Clear to end of screen key 


kt 


Clear thistab key 
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String C apabilities 



kT Set tab here key 

ku Cursorupkey 

10 Label of zeroth function key, if not fO 

11 Label of first function key, if notfl 

12 Label of first function key, if notf2 

ia Label of tenth function key, if not fio 

ie Cursorleftonecharacter 

n M ove cursor to lower-left corner 

le Cursor left%i characters 

lf Turn soft label s off 

lo Turn soft labelson 

mb Start blinking 

mc Clearsoft margins 

md Start bold mode 

me End ali modes such as so, us, mb, md, and mr 

mh Start halfbright mode 

mk Dark mode(Charactersinvisible) 

ml Set left soft margin 

mm Put terminal in meta mode 

mo Put terminal out of meta mode 

mp Turn on protected attribute 

mr Start reverse mode 

mr Set ri ght soft margin 

nd Cursor rightonecharacter 

nw C arriage return command 

pc Paddingcharacter 

pf Turn printer off 

pk Program key %1 to send string %2 asif typed by user 

pi Program key %1 to execute string %2 in locai mode 

pn Program soft label %1 to show string %2 

po Turn the printer on 

po Turn the printer onfor%i (<256) bytes 

ps Print screen contentson printer 

px Program key%i to send string %2 to computer 

n Reset string 1 to set terminal to sane modes 

r2 Reset string 2 to set terminal to sane modes 

r3 Reset string 3 to set terminal to sane modes 

ra D isableautomatic margins 

re Restare saved cursor position 

rf Reset string file name 



Stri ng C apabi I ities 



RF 


Request for input from terminal 


RI 


Cursor right %1 characters 


rp 


Repeat character %1 for %2 times 


rP 


Padding after character sent in replacemode 


rs 


Reset stri ng 


RX 


Turn offXON/XOFFflow control 


sa 


Set %1 %2 %3 %4 %5 %e%7 %8 %9 attri butes 


SA 


Enableautomatic margins 


se 


Save cursor positi on 


se 


End standout mode 


sf 


N ormai serali oneline 


SF 


N ormai serali %1 lines 


so 


Start standout mode 


sr 


Reverse serali 


SR 


Scroll back %1 lines 


st 


Set tabulator stop in ali rows at current column 


sx 


Turn on XON/XOFF flow control 


ta 


M ove to next hardware tab 


te 


Read in terminal description from another entry 


te 


End program that uses cursor motion 


ti 


Begin program that uses cursor motion 


ts 


Movecursorto column %1 of status line 


uc 


U nderline character under cursor and move cursor right 


ue 


End underlining 


up 


Cursor up oneline 


UP 


Cursor up%i lines 


US 


Start underlining 


vb 


Visiblebell 


ve 


N ormai cursor visi ble 


vi 


Cursor invi sible 


vs 


Standout cursor 


wi 


Setwindowfrom I i ne %1 to%2 and column %3to%4 


XF 


XOFF character if not "S 



T here are several ways of defining the control codes for stri ng capabilities: 
N ormai characters except - , \, and % represent themselves. 

A "x meansCtrl+x. Ctrl+A equalsl decimai, u meansaspecial code, x can beoneof the foli ovvi ng characters: 

e Escape (27). 

n Linefeed(lO). 

r Carriage return (13). 

t Tabulation (9). 
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b Backspace(8). 

f Form feed (12). 

0 Nuli character. A \xxx specifiesthe octal characterm. 

1 Incrementsparametersby one. 
r Single parameter capability. 

+ Add valueof next character to this parameter and do binary output. 

2 Do ASCII output of this parameter with afield width of 2. 
d Do ASCII output of this parameter with afield width of 3. 
% Print a % 



If you use binary output, then you should avoid the nuli character becauseit termi nates the stri ng. You should reset tabu lato r 
expansion if atabulatorcan be the binary output of a parameter. 

W arni ng: The precedi ng metacharactersfor parameters may bewrong; they documentivi inixtermcap, which may not be 
compati ble with Linux termcap. 

The block graphiccharacterscan bespecified by threestringcapabilities: 



as Start the alternative charset. 

ae Endit. 

ac Pai rs of characters. T he first character is the name of the block graphic symbol and 

thesecond character isits definition. 

Thefollowing namesareavailable: 

+ Rightarrow(>) 

Leftarrow(<) 

Downarrow(v) 
e Full square (#) 

i Latern (#) 

Upper arrow(-) 

Rhombus(+) 

a Chessboard (:) 

f D egree ( 1 ) 

g Plus-minus(#) 
h Square (#) 

j Rightbottom corner (+) 

k Right upper corner (+) 

ì Left upper corner (+) 

m Left bottom corner (+) 

n Cross (+) 

o U pper horizontal line { -) 

q M iddle horizontal line(-) 

s Bottom horizontal line {_) 

t Left tee (+) 

u Right tee(+) 

v Bottom tee (+) 

w N ormai tee (+) 

x Vertical line (_) 

Paragraph (???) 



tzfile 



Thevalues in parenthesesaresuggested defaultsthat areused by curses if thecapabilities are missing. 
SEEALSO 

termcap(3), curses(3), terminfo(5) 

Linux 

ttytype 

ttytype— Terminal name and device list. 
D ESC RIFTIO N 

The /etc/ttytype fileassociatestermcap/terminfo terminal typenameswith tty lines. Each li ne consistsof a terminal type, 
followed by whitespace, followed by a tty name (a device name without the nevi prefix). 

This associati on isused by the program tset(l) to set theenvironment variable term to the default terminal name for the 
user'scurrent tty. 

T his faci litywas desi gned for a traditi onal time-sharingenvironmentfeaturing character-cell termi nalshardwired to aU N IX 
minicomputer. It is little used on modem workstation and personal U N IXes. 

EXAMPLE 

A typical /etc/ttytype ÌS 

con80x25 ttyl 
vt320 ttys0 

FILES 

/etc/ttytype Thetty defi niti ons fi le 

SEEALSO 

getty(l), terminfo(5), termcap(5) 

Linux, 24 J uly 1993 

tzfile 

tzfìie— T i me zone i nformation. 
SYNOPSIS 

#include <tzfile.h> 

DESCRIPTION 

The ti me zone i nformation filesused by tzset(3) begin with bytes reserved for future use, followed by sixfour-byte valuesof 
type long, written in a "standard" byteorder (thehigh-order byteof thevalueiswritten first). Thesevalues are, in order 

tzh ttisgmtcnt T he number of G M T/local indicatorsstored in thefile. 

tzh_ttisstdcnt The number of standard/wall indicatorsstored in thefile. 

tzhieapcnt T he number of leap secondsforwhich data is stored in thefile. 

tzn_timecnt The number of "transition times" for which data is stored in thefile. 

tzn_typecnt The number of "locai timetypes" for which data is stored in thefile (must not bezero). 

tzn_cnarcnt The number of characters of "timezoneabbreviation strings" stored in thefile. 
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Thepreceding header is followed by tzh_timecnt four-bytevaluesof typeiong, sorted in ascendi ng order. Thesevaluesare 
written in "standard" byte order. Each isused asatransition time(asreturned by time(2)) atwhich therulesfor computing 
locai timechange. N ext cometzh_timecnt one-bytevaluesof typeunsigned char; each onetellswhich of the different types 
of "locai ti me" types descri bed in the fi le is associ ated with thesame-indexed transition time. Thesevalues serve asindices 
into an array of ttinf o structuresthat appearsnext in the fi le; thesestructures are defined asfollows: 

struct ttinfo { 

long tt_gmtoff; 

int tt_isdst; 

unsigned int tt^abbrind; 

>; 

Each structure is written asafour-bytevaluefortt_gmtoff of type long, in a standard byte order, followed by aone-byte 
valuefor tt_isdst and a one-bytevaluefortt_abbrind. In each structure, ttjmtoff givesthenumber of secondsto beadded 
to GMT, tt_isdst tellswhether tm_isdst should beset by iocaitime(3) and tt_abbrind servesasan index into the array of 
timezoneabbreviation charactersthatfollow the ttinfo structuresin the file. 

Then therearetzn_ieapcnt pairsof four-bytevalues, written in standard byteorder; the first valueof each pair givesthetime 
(asreturned by time(2)) atwhich a leap second occurs; thesecond gives the total number of leap secondsto beapplied after 
thegiven time. The pairsof values are sorted in ascendi ng order by time. 

Then therearetzn_ttisstdcnt standard/wall indicators, each stored asaone-bytevalue; they tei I whether thetransition times 
associated with locai timetypeswerespecified as standard timeorwall clock ti me and areused when a ti me zone fi le isused 
in handling POSIX-styletimezoneenvironment variables. 

Finally, therearetzh_ttisgmtcnt GMT/local indicators, each stored asaone-bytevalue; they teli whether thetransition times 
associated with locai timetypeswerespecified asGM T or locai ti me and areused when a ti me zone fi le isused in handling 
POSIX-styletimezoneenvironment vari ables. 

ucaitime uses the first standard-ti me ttinfo structure in the fi le (or si mply the first ttinfo structure in theabsenceof a 
standard-ti me structure) if either tzn_timecnt iszero orthetimeargument islessthan the first transition timerecorded in the 
file. 

SEEALSO 

newctime(3) 

utmp, wtmp 

utmp, wtmp— Login records. 
SYNOPSIS 

#include <utmp.h> 

D ESC RIPTIO N 

T he utmp file allows you to discover information aboutwho iscurrently usi ng the system. Theremay bemoreuserscurrently 
usi ng the system because notali programs use utmp logging. 

Warning: utmp must not bewritable because many system programs depend on itsintegrity. You riskfaked system logfiles 
and modificationsof system filesif you leaveutmp writableto anyuser. 

T he file is a sequence of entries with thefollowing structure declared in the include fi le 

#define UTJJNKNOWN 0 

#define RUN_LVL 1 

#define BOOT_TIME 2 

#define NEW_TIME 3 

#define OLD_TIME 4 



utmp, wtmp 
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#define INIT_PROCESS 5 
#define LOGIN_PROCESS 6 
#define USER_PROCESS 7 
#define DEAD_PROCESS 8 

#define UT_LINESIZE 12 
#define UTJIAMESIZE 8 
#define UTHOSTSIZE 16 

struct utmp { 

short ut_type; /* type of login */ 

pid_t ut_pid; /* pid of process */ 

char ut_line[UT_LINESIZE] ; /* device name of tty - "/dev/" */ 

char ut_id[2]; /* init id or abbrev. ttyname */ 

time_t ut_time; /* login time */ 

char ut_user[UT_NAMESIZE] ; /* user name */ 

char ut_host[UT_HOSTSIZE] ; /* host name for remote login */ 

long ut_addr; /* IP addr of remote host */ 

}; 

T his structure gives the name of the special fi le associateci with the user's terni inai, theuser's login name, and the time of 
login in theform of time(2). Stri ngfields are termi nateci by \o if they areshorterthan thesizeof thefield. 

Thefirst entriesevercreated resultfrom init(8) processing imttab(5). Beforean entry is processed, though, init(8) cleans 
up utmp by setting ut_type to dead_process, clearing ut_user, utjiost and ut_time with nuli bytesfor each record that utjiype 
isnotDEAD_PRocEss or run_lvl and whereno process with PID ut_pid exists. If no empty record with theneeded utj.d can be 
found, init createsa new one. It setsut_id from theinittab, ut_pid and ut_time to thecurrent values, and ut_type to 

INIT_PROCESS. 

getty(8) locates the entry by the PID , changesut_type to login_process, changesuttime, setsut„iine and waitsfor 
connection to beestablished. iogin(8), after a user hasbeen authenticated, changesut_type to user_process, changes ultime, 
and setsut host and ut_addr. D ependi ng on getty(8) and iogin(8), records may belocated by ut_iine instead of the 
preferable ut_pid. 

When init(8) findsthat a process hasexited, it locatesits utmp entry by ut_pid, setsutjtype to dead_process, and clears 
ut_user, ut_host, and ut_timewith nuli bytes. 

xterm(l) and other terminal emulators directly create a user_process record and generate the ut_id by using thelasttwo 
letters of /dev/ttyp%c or by using p%d for /dev/pts/%d. 

If they fi nd a dead_process for thislD, they recycleit; otherwise, they create a new entry. If they can, they wi II mark it as 
dead_process on exi ti ng and it isadvised that they nuli ut iine, ultime, ut_user, and utjiost aswell. 

xdm(8) should not create an utmp record becausethereisno assigned terminal. Letti ng it create one wi II result in troublesuch 
asfinger: cannot stat /dev/machine.dom. It should create wtmp entries, though, just like ftpd(8) does. 

teinetd(8) setsup a login_process entry and leavestherest to iogin(8) as usuai. After theTelnet session ends, teinetd(8) 
cleansup utmp in the described way. 

The wtmp fi le records ali loginsand logouts. Its format isexactly like utmp except that a nuli usernameindicatesa logout on 
theassociated terminal. Furthermore, the terminal name- with usernameshutdown or reboot indicates a system shutdown or 
reboot and thepair of terminal names ■ i - /"}" logstheold/new system ti me when date(l) changesit. wtmp ismaintained by 
ìogin(l) and init(l) and some variati on of getty(l). N either of theseprogramscreatesthefile, so if it isremoved, record- 
keeping isturned off. 



FILES 



/var/run/utmp 
/var/log/wtmp 
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CONFORMINO TO 

Linux utmpentriesconform neitherto v7/BSD norto SYSV:Theyareamixof thetwo. v7/BSD hasfewer fields; most 
importantly, it lacks ut_type, which causes native v7/BSD-like programsto display (for example) dead or login entries. 
Further there is no configuration filethat allocates slots to sessions. BSD does so becauseit lacks ut_id fields. In Linux (as in 
SYSV), the ut_id field of a record will never change once it is set, which reserves that slot without needing a configuration 
file. Clearing ut^id may result in raceconditionsleading to corrupted utmp entries and potenti al security holes. Clearing the 
previously mentioned fields byfillingthem with nuli bytes is not required bySYSV semantics, but itali owsyou to run many 
programs that assume BSD semantics and that do not modify utmp. Linux uses the BSD conventionsfor line contents. SYSV 
onlyuses the type field to mark them and logs informative messagessuch asnew time in the li ne field. SYSV hasonemore 
field to log the exit status of dead processes. utunknown seemsto bea Linux i nventi on. There is no type accounting in Linux. 
SYSV hasno ut_host or ut_addr fields. U nlike various other systems, whereutmp loggingcan bedisabled by removingthe 
file, utmp must alwaysexist on Linux. If you want to disablewho(l), then do not makeutmp world readable. 

RESTRICTIONS 

The fi le format is machine dependent, so it isrecommended that it beprocessed only on the machine archi tecturewhereit 
got created. 

SEEALSO 

ac(l), date(l), last(l), login(l), who(l), getutent(3), init(8) 

20 Juiy 1996 
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uuencode— Format of an encoded uuencodefile. 
DESCRIPTION 

Files output by uuencode(l) consist of a header li ne, followed byanumber of body lines, and a trailer line Theuudecode(l) 
command will ignoreany lines precedi ng the header or following the trailer. Lines precedi ng a header must not, of course, 
look li ke a header. 

The header lineisdistinguished by having the first sixcharactersbegin. The word begin is followed by a mode (in octal) and 
a stri ng that names the remote fi le. A space separates the th ree items in the header line. 

The body consistsof a number of lines, each at most 62 characters long (including the trai ling newli ne). These consist of a 
character count, followed by encoded characters, followed by a newli ne Thecharacter count is a single printing character 
and representsan integer, the number of bytes the rest of the line represents. Such integers arealwaysin therangefrom 0 to 
63 and can be determined by subtracting the character space (octal 40) from the character. 

Groupsof th ree bytes are sto red in four characters, six bits per character. Ali are offset by a space to make the characters 
print. Thelast line may beshorterthan thenormal 45 bytes. If the size isnot a multiple of three, thisfact can be determined 
by the valueof the count on thelast line. Extra garbage will beincluded to make the character counta multi pie of four. The 
body is termi nated by a line with a count of zero. This line consists of one ASC 1 1 space. 

The trailer li ne consistsof end on a lineby itself. 
SEEALSO 

uuencode(l), uudecode(l), uusend(l), uucp(l), maìl(l) 

HI STORY 



The uuencode fi le format appeared in BSD 4.0. 
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xF86Config— Confi guration file for X Free66. 
D ESC RIPTIO N 

XFree86 uses a configurati on fi I e cai I ed xF86Config for itsinitial setup. This confi guration file is searched for in the followi ng 
places: 

/etc/XF86Config 

<X Ro o t >/lib/X11/XF86Config.host nane 
<XRoot >/lib/X11/XF86Config 

<XRoot> refersto theroot oftheXll instali tree 

T his file is composed of anumberof sections Each section hastheform: 

Section "Sect i onName " 
Secti onEntry ... 
EndSection 



The section namesare 
Files 

ServerFlags 

Keyboard 

Pointer 

Monitor 

Device 

Screen 



Filepathnames 
Server fi ags 

Keyboard confi guration 
Pointer confi guration 
M onitordescription 
Graphi cs devi ce descri ption 
Screen configuration 



The Fiies section isused to specify the default font path and thepath to the RGB database. Thesepathscan also beset from 
thecommand li ne (seexserver(l)). The entries avai lablefor this section are 

FontPatn "path" Sets the search path for fonts. This path isa comma-separated list of directoriesthat the X 

server searches for font databases. M ultiple FontPath entries may bespecifi ed, and they will 
be concatenated to bui Id up the fontpath used by the server. 

X11R6 allowstheX server to request fonts from a font server. A font server is specifi ed by 
piaci ng a "<t r a n s >/<ho s t n a me > : <p o r t _ n u mb er >" entry into thefontpath. For example, the 
fontpath 

7usr/X11R6/lib/X11/fonts/misc/,tcp/zok:7100" 

tellstheX server to first try to locate the font in the locai directory /usr/xnR6/iib/xn/ 
fonts/misc. If that fai Is, then request the font from the font server runningon machinezok 
listening for connections on TC P port number 7100. 
RGBPatn "path" Sets the path name for the RG B color database. 

The serverFiags section isused to specify some miscellaneousX server options. The entries available for this section are 



NoTrapSignals 



DontZap 



DontZoom 



ThispreventstheX server from trappinga rangeof unexpected fatai signalsand exiting 
cleanly. Instead, theX server will di e and drop core where the fault occurred. The default 
behavior isfortheX server exit cleanly but stili drop a core file. In general, you never want 
to use this option unlessyou are debugging an X server problem. 
T h is di sai I ows the use of the C tri -(A It+B ackspace sequence. T h i s sequence al I ows you to 
terminate theX server. Setti ng Dontzap allowsthiskey sequence to bepassed to cliente 
T his disallows the use of the Ctrl-rAlt+Key-pad-Plus and Ctrl+Alt+Keypad-M inussequences. 
Thesesequences allow you to switch between video modes. Setti ngnontzoom allowsthese 
key sequencesto be passed to clients. 
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TheKeyboard section isused to specify the keyboard input device, parameters, and some default keyboard mappingoptions. 
T h e en tri es avai I abl e f o r th i s secti o n are 



Protocol " k b d - protocol 



AutoRepeat del ay rate 



ServerNumLock 



k b d - protocol may beeither standard orxqueue. xqueue is specifi ed when usingtheevent 
queue driver on SVR3 orSVR4. 

Changes thebehavior of the autorepeat of the keyboard. T hi sdoesnot work on ali 
platforms. 

ForcestheX server to handlethenumlock key internai ly. The X server sends a different set 
of keycodesforthenumpad when thenumlock key isactive This enables applicationsto 
makeuseof thenumpad. 

LeftAlt mapping RightAlt mappi ng AltGr mapping 
ScrollLock mapping RightCtl mapping 

Allows a default mappi ngto be set for the precedi ng keys(notethat AitGr isasynonym for RightAlt). Thevaluesthat may be 
specified for mappi ng are 

Meta 

Compose 

ModeShift 

ModeLock 

ScrollLock 

Control 

Thedefault mapping when none of theseoptions are specified is 
LeftAlt M età 
RightAlt Meta 
ScrollLock Compose 
RightCtl Control 

xLeds led ... M akes i ed available for clients instead of using the traditional function (Serali Lock, C aps 

Lock, and N um Lock). i ed isa list of numbers in the range 1 to 3. 

vTSysReq E nables the SYSV-style VT switch sequencefor non-SYSV systemsthat support VT 

switching. This sequenceis Alt- SysRq followed by a function key (Fn). This prevents the X 
server trapping the keysused for thedefault VT switch sequence. 

vnnit "command" Runscommand after the VT used by the server has been opened. T he command stri ng is 

passed to /bin/sti -c and is run with thereal user'sID with stdin and stdout set to thevT. 
Thepurposeof thisoption isto allow system -dependentVT initialization commandsto be 
run. 0 ne example isa command to disablethetwo-key VT switching sequence that isthe 
default on somesystems. 

The Pointer section isused to specify the pointer devi ce and parameters. The entri es available for this section are 
protocol "protocol -type " Specifies the pointer device protocol type. T he protocol typesavailableare 

BusMouse 

Logitech 

Microsoft 

MMSeries 

Mouseman 

MouseSystems 

PS/2 



XF86Config 



1203 



MMHitTab 

Xqueue 

OSMouse 

Oneshould specify BusMouse for the Logitech bus mouse. Also, many newer Logitech serial miceuseeither the Microsoft or 
MouseMan protocol, xqueue should bespecified hereif itwasused in theKeyboard section. osniouse refersto the event- driver 
mouse interface availableon SCO'sSVR3. Thismay optionally befollowed by a number speci fying the number of buttons 
the mouse has. 



Specifies the devi ce the server should open for pointer input (such as/dev/ttyoe 
or /dev/mouse). A deviceshould not bespecified when usi ng the Xqueue or 
OSM ouse protocol s. 

Setsthebaud rate of the seri al mouse to rate. Formicethatallow dynamicspeed 
adjustments(such as Logitech), thebaud rateischanged in the mouse. 
Otherwise, the rate issimply set on the computerà si de to allow micewith non- 
standard rates (the standard rate is 1200). 

Enablestheemulation of thethird mouse button for micethat only havetwo 
physical buttons. Thethird button isemulated by pressing both buttons 
simultaneously. 

Sets th e ti m e ( i n m i 1 1 i seco nds) that th e server wai ts bef o re deciding if two 
buttons werepressed "simultaneously" when three-button emulation isenabled. 
The default ti me-out is50ms. 

H andles micethat send left+right eventswhen the middle button isused (such as 
some Logitech M ouseman mice). 

Sets the number of moti on/button-events the mouse sends per second. Thisis 
currently only supported for some Logitech mice. 
Thisoption clearstheDTR lineon the serial portused by the mouse This 
option isonlyvalidforamouseusingtheMousesystems protocol. Somedual- 
protocol micerequireDTR to becleared to operate in Mousesystems mode. N ote, 
in versionsof XFree86 priorto 2.1, thisoption also cleared the RT S line. A 
separate ciearRTs option hassincebeen added for micethat requirethis. 
Thisoption clearstheRTS lineon the serial port used by the mouse Thisoption 
is only vai id for a mouse usi ng the Mousesystems protocol. Somedual-protocol 
mice require both DTR and RTSto becleared to operatein Mousesystems mode. 
Both theciearDTR and ciearms options should beused for such mice 

The Monitor sections are used to define the specificationsof a monitor and a list of video modessuitablefor usewith a 
monitor. M orethan one Monitor section may bepresent in an xF86Contig file. The entriesavailablefor this section are 

This specifies a stri ng by which the monitor can bereferred to in alater screen 
section. Each Monitor section should haveauniquelD string. 
This optional entry specifies the monitor's manufacturer. 
This optional entry specifies the monitor's model. 
Givestherangesof horizontal syncfrequencies supported by the monitor, 
hori zsync- range may be a comma-separated listof either di screte values or ranges 
ofvalues.A range of values is two values separated byadash. By default, the 
values are in unitsof kH z. They may bespecified in M H zor Hz if M H zor H zis 
added to the end of the li ne. The data given here isused by theX server to 
determine if video modes are within the specifications of the monitor. This 
information should be available in the monitor's handbook. 



Device "poi nter-dev" 
BaudRate rate 

Emulate3Buttons 

Emulate3Timeout timeout 

ChordMiddle 
SampleRate rate 
ClearDTR 

ClearRTS 



Identif ier "I D string" 

VendorName "vendor " 
ModelName "model 11 
HorizSync hori zsync- range 
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VertRefresh vertrefresh-range 



Gamma g a mma -vai u e s 



Mode "name 1 



DotClock clock 

HTimings hdisp hsyncst art hsyncend htotal 
VTimings vdisp vsyncst art vsyncend vtota 
Flags "fi a g " ... 



G ives the ranges of vertical refresh frequenti es supportai by the monitor, 
vertrefresh-range maybeacomm a- separateci list of either discrete values 
or ranges of values. A rangeof values istwo values separateci by adash. By 
default, the values are in unitsof Hz. They may be specified in M Hz or 
kHz if M Hzor kHz isadded to the end of the li ne The data given hereis 
used by theX server to determine if video modesarewithin the 
specifi cationsof the monitor. Thisinformation should be available in the 
monitor'shandbook. 

This isan optional entry that can beused to specify the gamma 
correction for the monitor. It may be specified as either a single value or 
asthree separate RGB values. Notali X servers are capableof using this 
information. 

Indicates the start of a multi-line video modedescription. The mode 
description isterminated with an End-M odeline. The modedescription 
consists of the following entri es: 
The dot clock rateto beused for the mode. 
Specifi es the horizontal ti mi ngs for the mode. 
Specifi es the verti cai ti m i ngs for the mode. 

Specifies an optional set of mode flags mteriace indicates that the mode 
is interlaced. Doubiescan indicates a modewhereeach scanline is doubled. 
+HSync and -HSync can beused to select the polarity of the H Sync signal. 
+vsync and -vsync can beused to select the polarity of the VSync signal. 
composite can beused to specify composite sync on hardware wherethisis 
supported. Additionally, on some hardware, +csync and -csync may be 
used to select the composite sync polarity. 

A single line format for specifyi ng video modes. The mode- descr pt i on is 
in four sections, the first three of which are mandatory. The first isthe 
pixel clock. T hisis a single number specifying the pixel clock rate for the 
mode The second section isa list of four numbers specifying the 
horizontal timings. These numbers are the hdisp, hsyncstart, hsyncend, 
htotai. T he third section isa list of four numbers specifying the vertical 
timings. These numbers are vdisp, vsyncstart, vsyncend, vtotai. The final 
section isa list of flags specifying other eh aracteri sti cs of the mode, 
mteriace indi cates that the mode is interlaced. Doubiescan indicatesa 
modewhereeach scanline is doubled. +HSync and -HSync can beused to 
select the polarity of theHSync signal. +vsync and -vsync can beused to 
select the polarity of thevsync signal. composite can beused to specify 
composite sync on hardware where this issupported. Additionally, on 
some hardware +csync and -csync may be used to select the composite 
sync polarity. 

The Device sections are used to define a graphics device (video board). M orethan one Device section may bepresent in an 
xF86Contig file. T he entries avai lable for this section are 



Modeline "name" mode- descr i pt i on 



Identif ier "I D stri n g " 

Vendo rName "vendo r " 
BoardName "model " 
Chipset "chi pset-type" 



This specifies a stri ng by which the graphics device can bereferred to in a 
laterscreen section. Each Device section should haveauniquelD string. 
This optional entry specifies the graphics device'smanufacturer. 
This optional entry speci f i es th e n am e of th e graph i cs devi ce 
Thisoptional entry specifi esthechipset used on the graphics board. In 
mosteases, this entry isnot required becausetheX servers will probe the 
hardware to determinethechipsettype. 
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Thisoptional entry specifies the typeof RAM DAC used on the graphics board. 
Thisisonly used by a few of theX servers, and in most cases, it isnot required 
becausetheX servers will probe the hardware to determinethe RAM DAC type 
where possi ble. 

Thisoptional entry specifies theRAM DAC speed rating (which isusually 
printed on the RAM DAC chip). The speed isin M Hz. Thisisonly used bya 
few of theX servers and only needsto bespecified when the speed rating of the 
RAM DAC is different from the default built in to theX server. 
Specifies the dotclocksthat are on your graphi cs board. The clocks are in MHz 
and may bespecified asafloating-point number. Thevalueisstored internai ly to 
thenearest kHz. Theordering of the clocks is important. It must match the 
order in which they areselected on the graphics board. M ulti pie ciocks lines may 
bespecified. Forboardswith programmable clock chips, the ciockchip entry 
should beused instead of this A ciocks entry isnot mandatory for boardswith 
non- programmable clock chips but is highly recommended becauseit prevents 
the clock probi ng phaseduring server startup. This clock probing phasecan 
cause problems for some monitora 

Thisoptional entry isused to specify the clock chip type on graphics boardsthat 
have a programmable clock generator. OnlyafewX servers support program- 
mable clock chips. For detai Is, see the appropriate X server manual page. 
Thisoptional entry runs co minanti to set the clock on the graphics board instead of 
usi ng the internai code. Thecommand stri ng must consist of the full pathname 
(and no flags). W hen usi ng this option, a ciocks entry is required to specify 
which clock values areto bemadeavailableto the server (up to 128 clocks may 
bespecified). The optional text ci ock valueis to teli the server that c o mma n d must 
berun to restare the text-mode clock at server exit (or when VT switching). 
textcì ock must match oneof the values in theciocks entry. This parameter is 
required when theclock used fortext mode is a programmable clock. 
Thecommand isrun with thereal user'sID with stdin and stdout setto the 
graphics console devi ce. Two arguments are passed to thecommand. The first is 
theclock frequency in M Hz asafloating-point number andthesecond isthe 
index of theclock in theciocks entry. Thecommand should return an exit status 
of 0 when successful and something in the range 1-254 otherwise. 
Thecommand isrun when theinitial graphics mode is set and when changing 
screen resolution with thehotkey sequences. If the program failsat initialization, 
the server exits. If it fai Is duri ng a modeswitch, the mode switch isaborted but 
the server keepsrunning. It isassumed that if thecommand fails, theclock has 
not been changed. 

Thisoptional entry allows the user to select certain optionsprovided bythe 
drivers. M ultipleoption entriesmay begiven. Thesupported values for 
opti onstri ng aregiven in the appropriate X server manual pages. 
Thisoptional entry specifies the amount of video RAM that is instai led on the 
graphics board. This ismeasured in kilobytes. In most cases, this isnot required 
becausetheX server probes the graphics board to determ i ne th i s quanti ty. 
This optional entry specifies the base address of the video Bl 0 S for the VGA 
board. This address isusually OxCOOOO, which is the default the X servers use. 
Somesystems, particularly those with on-board VGA hardware, havetheBIOS 
located atan alternate address, usually OxEOOOO. If your video BIOS isatan 
address otherthan OxCOOOO, you must specify the base address in thexF86Config 
file. N otethat someX servers don't access the BIOS at ali and those that do only 
use the BIO S when searching for information during the hardware probe phase. 
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MemBase bas eaddr ess 

IOBase baseaddress 
DACBase baseaddress 
POSBase baseaddress 
COPBase baseaddress 
VGABase baseaddress 

Instance number 

Speedup sei e c t i or 

S3MNAdjust MN 
S3MClk clock 
S3Ref Clock clock 



This optional entry specifiesthememory base addressof a graphics board's linear 
frame buffer. T hi s entry isonly used by a few X servers, and the interp retati on of 
this base address may be different for different X servers. Refer to the appropriate 
X server manual page for details. 

This optional entry specifies the IO baseaddress. This entry isonly used for a 

fewX servers. Referto the appropri ateX server manual page for details. 

This optional entry specifies the D AC baseaddress. This entry isonly used for a 

fewX servers. Referto the appropri ateX server manual page for details. 

This optional entry specifies the POS baseaddress. This entry isonly used for a 

fewX servers. Referto the appropri ateX server manual page for details. 

This optional entry specifies the coprocessor baseaddress. This entry isonly used 

forafewX servers. Referto the appropri ateX server manual page for details. 

This optional entry specifies the VGA memory baseaddress. This entry isonly 

used for a few X servers. Refer to theappropriateX server manual page for 

details. 

Thisoptional entry specifies the instance (which indicates if the chip is 
integrated on the motherboard or on an expansion card). This entry isonly used 
forafewX servers. Referto theappropriateX server manual page for details. 
Thisoptional entry specifies the sei ection of speedupsto beenabled. This entry 
isonly used forafewX servers. Referto theappropriateX server manual page for 
details. 

Thisoptional entry isspecificto the S3 X server. For details, referto the 
XF86_S3(1 ) manual page. 

Thisoptional entry isspecificto the S3 X server. For details, referto the 
XF86_S3(1) manual page. 

Thisoptional entry isspecificto the S3 X server. For details, referto the 
XF86„S3(1) manual page. 



Driver dr i ver ■ name 



Thescreen sections are used to specify which graphics boards and monitors are used with a parti cularX server and the 
confi guration in which they areto beused. The entries availablefor this section are 

Each screen section must begin with a Driver entry, and the d r ì ver - name given in 
each screen section must beunique. The dr i ver - name determi nes which X server 
(or driver type within an X server when an X server supports more than one 
head) readsand uses a particular screen section. The driver namesavailableare 
Accel 
Mono 
SVGA 
VGA2 
VGA16 

Accei isused by ali the accel erated X servers (seexF86_Accei(l)). Mono isused by 
thenon-VGA mono driversin the 2-bit and 4-bit X servers (seexF86_Mono(l) and 
xf86_vgai6(1)). vga2 and vgai6 are used by the VGA driversin the 2-bit and 4-bit 
X servers. svga isused by the xf86_svga X server. 
Specifies which graphics device description isto beused. 
Specifies which monitor description isto beused. 
Thisoptional entry overridesthe default screen numberingin a multi-headed 
confi guration. The default numbering is determi ned by theorderingof the 
screen sections in the xF86Conf ig file. To override this, ali relevant screen 
sections must havethis entry specifi ed. 



Device devi ce- i d 
Monitor mo n i t or ■ i d 
ScreenNo scr num 



XF86Config 



Sets the inactivity time-out for the blanking phaseof the screensaver, ti me isin 
minutes, and thedefault is 10. T his is equivalent to theX server's -sflag, and the 
valuecan bechanged at runtimewith xset(l). 

Sets the inactivity time-out for the "suspend" phaseof the screensaver, t me isin 
minutes, thedefault is 15, and it can bechanged at runtimewith xvidtune(l). This 
isonly suitablefor VESA DPM S compatiblemonitorsand isonly supported 
currently bysomeX serverà The"power_saver" option must be set for this tobe 
enabled. 

Sets the inactivity time-out for the "off" phaseof the screensaver, ti me isin minutes, 
the default is 30, and it can bechanged at runtimewith xvidtune(l). This isonly 
suitablefor VE SA D PM S compatiblemonitorsand isonly supported currently by 
someX serverà The"power_saver" option must be set for this to be enabled. 
This entry isa subsection that isused to specify some display speci fic parameters. 
Thissubsection isterminated by an Endsubsection entry. ForsomeX servers and 
drivers (those requi ri ng a list of video modes), thissubsection ismandatory. ForX 
serversthat support multiple display depths, morethan one Display subsec-tion can 
bepresent. W hen multiple Display subsectionsarepresent, each must haveaunique 
Depth entry. The entriesavailable for the Display subsection are 
This entry ismandatory when morethan oneDispiay subsection ispresentin a 
screen section. W hen only one Display subsection ispresent, it speci fi es the default 
depth wheretheX server will run. W hen morethan oneDispiay subsection is 
present, thedepth determi neswhich getsused by theX server. The subsection used 
istheonematchingthedepth atwhich theX server is run. Notali X servers(or 
drivers) support morethan onedepth. Permitted valuesforbpp are 8, 15, 16, 24, and 
32. N ot ali X servers (or drivers) support ali thesevalues. b p p valuesof 24 and 32 are 
treated equivalente by thoseX servers that support them. 
This optional entry specifies the relative RGB weightingto beused for an X server 
runningat 16bpp. Thismay also bespecified from thecommand line {see 
xFree86(l)). Values supported by most 16bpp X servers are 555 and 555. For further 
details, referto the appropri ateX server manual page. 

This optional entry specifies the vi rtual screen resolution to beused. xdi m must bea 
multiple of either 8 or 16 formostcolorX servers and a multiple of 32 forthe 
monochromeX server. Thegiven valueisrounded down if this isnot the case For 
most X servers, video modes that aretoo largefor the specified virtual sizeare 
rejected. If this entry is not present, the vi rtual screen resolution isset to accommo- 
dateall thevalid video modes given in theniodes entry. SomeX servers do not 
support this entry. Referto the appropriate X server manual pages for details. 
This optional entry sets the upper-left corner of the ini ti al display. This isonly 
relevantwhen the virtual screen resolution isdifferentfrom the resolution of the 
initial video mode. If this entry is not given, then theinitial display iscentered in the 
virtual display area. 

T his entry ismandatory for most X servers, and it specifies the list of video modesto 
use. The video mode names must correspond to those specified in the appropriate 
Monitor section. MostX servers delete modesfrom this list that don't satisfy various 
requi rements. The first valid mode in this list is the default display mode for startup. 
The list of vai id modes isconverted internally into acircular list. It ispossibleto 
switch to thenext modewith Ctrl+Alt+Keypad Plus and to the previous mode with 
Ctrl+Alt-rKeypad M inus. 

Thisoptional entry isspecificto the S3 server only. It can beusedto changethe 
default VC LK i nvert/non- in vert state for individuai modes. If "modename " is "", the 
setti ng appi iesto ali modesunlessoverridden by later entri es. 
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EarlySC modename 0|1 



BlankDelay modename vai u e 1 vai u e 2 



Visual v i s u a I - n a me 



Option opti onstri ng 

Black red green blue 
White red green blue 



Thisoptional entry isspecificto the S3 server only. Itcan beusedto changethe 
default Eariysc setti ngfor individuai modes. This setti ng can affectscreen wrapping. 
If "modename " is " " , the setting applies to ali modes unlessoverridden by later entri es. 
Thisoptional entry isspecificto the S3 server only. Itcan beusedto changethe 
default blank delay setti ngsfor individuai modes. This can affectscreen wrapping. 
vai u e i and vai ne 2 must be integers in therangeO-7. If "modename ■ is "", the setting 
applies to ali modes unlessoverridden by later entri es. 

Thisoptional entry sets the default root visual type. Thiscan also bespecified from 
thecommand li ne (seexserver(l)). The visual types availablefor 8bpp X serversare 

(default ÌS PseudoColor): 

StaticGray 

GrayScale 

StaticColor 

PseudoColor 

TrueColor 

DirectColor 

T he vi sual type avai lable for the 16bpp and 32bpp X servers is TrueColor. 

The visual type availablefor the lbppX server isstaticGray. 

The visual types available for the4bpp X server are (default ispseudocoior): 

StaticGray 
GrayScale 
StaticColor 
PseudoColor 

Thisoptional entry allows the user to select certain optionsprovided by thedrivers. 
M ulti pie option entri es can begiven. Thesupported values for opti on - st ri ng are 
given in the appropri ateX server manual pages. 

This optional entry allows the "black" color to be speci fi ed. This is only supported 
with theVGA2 driver in thexF86_Mono server (for details, seexF86jiono(l)). 
T his optional entry allows the "white" color to be speci fi ed. T his is only supported 
with theVGA2 driver in thexF86_Mono server (for details, seexF86_Mono(l)). 



Foran exampleof an xFseconfig file, see the fi le instai led as<xRoot>/iib/xn/xF86Config.eg. 



FILES 



/etc/XF86Config 

<XRoot>/lib/X11/XF86Config. hostname <XRoot>/lib/X1 1 /XF86Conf ig 

N otethat <xRoot> refersto the root of the X 11 instali tree. 



SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86_SVGA<1), XF86_VGA16<1), XF86_Mono(l), XF86_S3<1), XF86_8514<1), XF86_Mach8(l), 
XF86_Mach32(l), XF86_P9000(1), XF86_AGX(1), XF86_W32<1) 



AUTHORS 

Referto thexFree86(l) manual page. 
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intro 

intro— Introduction to games. 
D ESC RIPTIO N 

Thischapter describes ali the games and funny little programsavailableon the system. 
AUTHORS 

Look at the headerof the manual page for the authors and copyright conditions. Notethatthesecan bedifferentfrom page 
to page! 

Linux, 24 J uly 1993 

banner 

banner— Print large banner on printer. 
SYNOPSIS 

/usr/games/banner [ -wn ] message ... 

DESCRIPTION 

banner printsa large, hi gh-quality banner on the standard output. If the message isomitted, it promptsfor and reads one line 
ofits standard input. If -w isgiven, the output isscrunched down from awidth of 132 to n, suitablefor a narrow terminal. If 
n isomitted, itdefaultsto 80. 

The output should beprinted on a hard-copy device, up to 132 columnswide, with no breaks between thepages. The 
volume isgreat enough thatyou mightwant a printer or a fast hard-copy terminal, but if you are patient, adecwriter or 
other 300 baud terminal will do. 

BUGS 

Several ASCII charactersarenotdefined, notably <, >, [, ], \, {, }, , and Also, thecharacters \ and & arefunny- 
looki ng (but i n auseful way). 

The -woption isimplemented by skipping some rows and columns. Thesmaller it gets, the grainier the output. Sometimesit 
runsletterstogether. 

AUTHOR 

M ark H orton 

6 Junel993 

ddate 

ddate— Converts bori ngnormal datestofun Discordian dates. 
SYNOPSIS 

ddate 



ddate 



DESCRIVO N 

ddate prints the date in D iscordian date format. 

AUTHOR 

D mei theChaotic, a.k. a. Jeremy Johnson (mpython9gnu.ai.mit.edu). M odificationsfor U N IX by LeeH arvey Oswald Smith, 
K.S.C. Fivetonsof flax. 

55 Confusi on 3160 
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intro 

intro— Introduction to miscellany section. 
D ESC RIPTIO N 

T his chapter descri bes miscellaneous things such asnroff macro packages, tables, C header files, the file hierarchy, general 
concepts, and other thingsthat don't fit anywhere else. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions. Notethatthesecan bedifferentfrom page 
to page! 

Linux, 23 Aprii 1993 

ascii 

ascii— The ASC II character set encoded in octal, decimai, and hexadecimal 

D ESC RIPTIO N 

T he followi ng table contai ns the 128 ASC 1 1 characters. 
C program '\X' escapes are noted. 



Oct 


Dee 


Hex 


Char 


Oct 


Dee 


Hex 


Char 


000 


0 


00 


N U L '\0' 


100 


64 


40 


@ 


001 


1 


01 


SOH 


101 


65 


41 


A 


002 


2 


02 


STX 


102 


66 


42 


B 


003 


3 


03 


ETX 


103 


67 


43 


C 


004 


4 


04 


EOT 


104 


68 


44 


D 


005 


5 


05 


ENQ 


105 


69 


45 


E 


006 


6 


06 


AC K 


106 


70 


46 


F 


007 


7 


07 


BEL V 


107 


71 


47 


G 


010 


8 


08 


BS'\b' 


110 


72 


48 


H 


Oli 


9 


09 


HT V 


111 


73 


49 


1 


012 


10 


OA 


LF '\n' 


112 


74 


4A 


J 


013 


11 


OB 


VT '\V 


113 


75 


4B 


K 


014 


12 


OC 


FF '\f 


114 


76 


4C 


L 


015 


13 


OD 


CR V 


115 


77 


4D 


M 


016 


14 


OE 


SO 


116 


78 


4E 


N 


017 


15 


OF 


SI 


117 


79 


4F 


0 


020 


16 


10 


D LE 


120 


80 


50 


P 


021 


17 


11 


DC1 


121 


81 


51 


Q 


022 


18 


12 


DC2 


122 


82 


52 


R 


023 


19 


13 


DC3 


123 


83 


53 


S 


024 


20 


14 


DC4 


124 


84 


54 


T 


025 


21 


15 


NAK 


125 


85 


55 


U 


026 


22 


16 


SYN 


126 


86 


56 


V 



u et 


ri or 

u se 


n ex 


l nar 


u et 


D ec 


U OV 

n ex 


l nar 


027 


23 


17 


ETB 


127 


87 


57 


W 


030 


24 


18 


CAN 


130 


88 


58 


X 


031 


25 


19 


EM 


131 


89 


59 


Y 


032 


26 


1A 


SUB 


132 


90 


5A 


Z 


033 


27 


1B 


ESC 


133 


91 


5B 


[ 


034 


28 


1C 


FS 


134 


92 


5C 


Y\V 


035 


29 


1D 


GS 


135 


93 


5D 


] 


036 


30 


1E 


RS 


136 


94 


5E 




037 


31 


1F 


US 


137 


95 


5F 


- 


040 


32 


20 


SPACE 


140 


96 


60 




041 


33 


21 


I 


141 


97 


61 


a 


042 


34 


22 




142 


98 


62 


b 


043 


35 


23 


# 


143 


99 


63 


c 


044 


36 


24 


$ 


144 


100 


64 


d 


045 


37 


25 


% 


145 


101 


65 


e 


046 


38 


26 


& 


146 


102 


66 


f 


047 


39 


27 




147 


103 


67 


g 


050 


40 


28 


( 


150 


104 


68 


h 


051 


41 


29 


) 


151 


105 


69 


i 


052 


42 


2A 


* 


152 


106 


6A 


j 


053 


43 


2B 


+ 


153 


107 


6B 


k 


054 


44 


2C 




154 


108 


6C 


1 


055 


45 


2D 


- 


155 


109 


6D 


m 


056 


46 


2E 




156 


110 


6E 


n 


057 


47 


2F 


/ 


157 


111 


6F 


0 


060 


48 


30 


0 


160 


112 


70 


P 


061 


49 


31 


1 


161 


113 


71 


q 


062 


50 


32 


2 


162 


114 


72 


r 


063 


51 


33 


3 


163 


115 


73 


s 


064 


52 


34 


4 


164 


116 


74 


t 


065 


53 


35 


5 


165 


117 


75 


u 


066 


54 


36 


6 


166 


118 


76 


V 


067 


55 


37 


7 


167 


119 


77 


w 


070 


56 


38 


8 


170 


120 


78 


X 


071 


57 


39 


9 


171 


121 


79 


y 


072 


58 


3A 




172 


122 


7A 


z 


073 


59 


3B 




173 


123 


7B 


{ 


074 


60 


3C 


< 


174 


124 


7C 


1 


075 


61 


3D 




175 


125 


7D 


} 


076 


62 


3E 


> 


176 


126 


7E 




077 


63 


3F 


? 


177 


127 


7F 


DEL 
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HISTORY 

An ascii manual page appeared in version 7 AT&T U N IX. 
SEEALSO 

iso_8859_l(7) 

Linux 



bootparam 

bootparam— Introduction to boot-time parameters of theLinux kernel. 
DESCRIPTION 

TheLinux kernel acceptscertain command-lineoptionsor boot-time parameters at the moment it isstarted. In general, this 
isused to supply the kernel with informati on about hardware parameters that the kernel would not beableto determi neon 
its own, or to avoid or overridethevaluesthat the kernel would otherwisedetect. 

When the kernel is booted directly by the BIOS (say, from a floppy to which you copied a kernel usingcp zimage /dev/fdo), 
you haveno opportuni ty to specify any parameters. To take advantage of this possi bili ty, you haveto use software that isable 
to pass parameters, such as LI LO or loadlin. Fora few parameters, onecan also modify the kernel imageitself, using rdev; see 
rdev(8)for further details. 

The LI LO program (LlnuxLOader) written by Werner Al mesberger isthemostcommonly used. It hastheability to boot 
variouskernelsand sto res the confi gu rati on information in aplain textfile. (Seeiiio(8) and ino.conf(5).) LILO can boot 
DOS, OS/2, Linux, FreeBSD, and so on and isquiteflexible. 

Theother commonly used Linux loader is loadlin, which isa DOS program that hasthe capability to launch a Linux kernel 
from theDOS prompt (with boot args) assuming that certain resources are available. This isgood for peoplewho want to 
launch Linux from DOS. 

It is also very useful if you have certain hardware that relieson thesupplied DOS driver to put the hardware into a known 
state. A common exampleisSoundBlaster-compatible sound cardsthat requiretheD OS driver to twiddleafew mystical 
registersto put the card into aSB-compatiblemode. Booti ng DOS with thesupplied driver and then loading Linux from the 
DOS prompt with loadlin avoids the reset of the card that happensif onerebootsinstead. 

THE ARGUMENT LIST 

M ost of the boot args take the form of 
name[=val ue_l][,val ue_2]...[,val ue ll] 

name is a uni que keyword that isused to identify what part of the kernel theassociated values (if any) areto begiven to. 
M ultiple boot argsarejust a space- separated list of the precedi ng format. N otethelimit of 11 isreal becausethepresent code 
handlesonly 11 comma-separated parameters per keyword. (H owever, you can reuse the same keyword with up to an 
additional 11 parameters in unusually complicateci situations, assuming the setup function supportsit.) 

M ost of the sorti ng occurs in ìinux/init/main . c. First, the kernel checks to see if the argument is any of the special 
arguments root=, ro, ™, or debug. Themeaningof these special argumentsisdescribed later in thedocument. 

Then, it walks a list of setup functions (contai ned in thebootsetups array) to seeif the specified argument stri ng (such asfoo) 
isassociated with a setup function (foo_setupo) for a particular device or part of the kernel. If you passed the kernel the line 
f 00=3, 4, 5, 6, then the kernel searches thebootsetups array to seeif too i s regi stered . If it is, it cai Is the setup function 
associated with too (foo_setupo) and handsit the arguments 3, 4, s, and 6 asgiven on the kernel command line. 

Anythingof the form too=bar that isnotaccepted as a setup function asdescribed isthen interpreted asan environment 
variableto beset. A (useless?) exampleisto useTERM=vti0o as a boot argument. 
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Any remai ning argumentsthat werenot picked up by the kernel and were not interpreted asenvironment vari ables are then 
passed onto processone which is usuai ly theinit program. The most common argument that ispassed to theinit process is 
the word single, which instructs init to boot the computer in single-user mode and not launch ali the usuai daemons. Check 
themanual page for the versi on of init instai led on your system to seewhat argumentsit accepts. 

GENERAL NO N -D EVIC E-SPEC I FIC BOOTARGS 

no387 

Somei387 coprocessor chi pshavebugs that show up when used in 32-bit protected mode. 

Forexample, some of the early ULSI-387 chips cause soli d lockups while performi ng floating-point calculations. Usingthe 
'no387' boot arg causes Linux to ignorethemaths coprocessor even if you haveone. Of course you must then haveyour 
kernel compiled with math emulation supporti 

no-hlt 

Some of the early Ì486D X-100 chips h ave a probi em with the hit instruction in that they can't reliably return to operati ng 
modeafter this instruction isused. Usingthe 'no -hit 1 instruction tei Is Linux to just run an infinite loop when thereis 
nothing else to do and to not halt the CPU. This al lowspeople with thesebroken chipsto use Linux. 

root=. . . 

This argument tei Is the kernel what device i sto beused astheroot filesystem whi le booti ng. The default of this setti ng is 
determi ned at compi le ti me and usually isthevalueof theroot devi ce of the system that the kernel was built on. To override 
this value and selectthesecond floppy drive astheroot device, oneuses 'root=/dev/fdi '. (Theroot device can also beset 

usi ng rdev(8).) 

Theroot devi ce can bespecified symbolically or numerically. A symbol ic specification hastheform /dev/xxYN, wherexx 
designates the device type(hd for ST-506-compatiblehard disk with y in a-h; sd for SCSI -com pati ble disk with y in a-e; xd 
for XT-compatible disk with y either a or t>; fd for floppy disk with y the floppy drive num ber— tda isthe D 0 5 A: drive and 
fdi isB:), y isthe driver letter or number, and n isthe number of the parti ti on on this device (absent in the case of floppies). 

N otethat this has nothing to do with the designation of th esedevi ceso n your filesystem. The /dev/ part ispurely conven- 
tional. 

The more awkward and less portable numeric specification of the previous possi ble root devices in major/minor format is 
also accepted. (For example, /dev/sda3 is major 8, minor 3, so you can use root=ax803 asan alternative.) 

r o and r w 

Thero option tei Is the kernel to mount the root filesystem asreadoniy so that filesystem consistency check programs(fsck) 
can do their work on a qui escent filesystem. N o processescan writeto fileson the filesystem in questi on until it isre- 
mounted asread/writecapable, such asby mount -w -n -o remount /. (Seealso mount(8).) 

The ™ option tei I s the kernel to mount the root filesystem read/write. Thisisthe default. 

Thechoicebetween read-onlyand read/write can also beset usingrdev(8). 

debug 

Kernel messagesarehanded off to the kernel log daemon kiogd so that they can belogged to disk. M essageswith a priority 
aboveconsoie__iogievei arealso printed on theconsole. (Fortheselevels, see<iinux/kernei.n>.) By default, this variable is set 
to log anything moreimportant than debug messages. This boot argument causes the kernel to also print the messages of 
debug priority. The console log level can also beset at runtimeviaan option to kiogd. Seekiogd(8). 

r e s e r v e = . . 

This isused to protect I/O port regionsfrom probes. Theform of thecommand is 

reserve=i obase ,extent [,i obase ,extent ] . . . 
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In some machine, it might be necessary to prevent device driversfrom checkingfor devices (auto-probi ng) in aspecific 
region. T his may be because of hardware that reacts badly to the probi ng, hardware that would be mistakenly identified, or 
hardware you don't want the kernel to initialize. 

T he reserve boot-ti me argument specifiesan I/O port region that shouldn't beprobed. A device driver does not probe a 
reserved region unlessanother boot argument explicitly specifiesthat it do so. 

Forexample, the boot line 

reserve=0x300,32 blah=0x300 

keeps ali device drivers except the driver for biah from probi ng 0x300-0x31f. 

r a md i s k = . . . 

Thisoption is obsolete si nce Linux 1.3.48 orso. Itspecifiesthesizein kilobytesof the optional RAM disk device. For 
example, if onewantsto havea rootfilesystem on a 1.44M B floppy loaded into the RAM disk device, they use 

ramdisk=1440 

Thisoption is set at compi le ti me (default isno RAM disk), and can bemodified using rdev(8). 

mem=. . 

T he BIOS cali defi ned in the PC specification that returnstheamount of installed memory wasonly designaci to beableto 
report up to 64M B. Linuxusesthis BIOS cali at boot to determine how much memory is installed. If you havemorethan 
64M B of RAM installed, you can usethis boot argto teli Linux how much memory you have. Thevalueis in decimai or 
hexadecimal (prefix Ox), and the suffixes k (timesl024) or m (ti mes 1048576) can beused. Thefollowing quote from Linus 
describes the use of the mem= parameter: 

"The kernel will accept any mem=xx parameter you giveit, and if it turnsout that you lied to it, it will crash horribly sooner or 
later. The parameter indicates the highest addressable RAM address, so 'mem=0xi 000000' meansyou havel6M B of memory, 
forexample. Fora96M B machine thiswould bemem=0x6000000. 

NOTE: Some machines might use the top of memory for BIOS cachi ng or whatever, so you might not actually haveup to 
the full 96M B addressable. The reverse i salso true: Some chipsets will map thephysical memory that iscovered by the BIOS 
area into the area just past the top of memory, so thetop-of-mem might actually be96M B + 384KB, forexample. If you teli 
Linux that it has more memory than it actually does have, bad thingswill happen: maybe not at once, but surely eventually." 

reboot=warm 

Since2.0.22, a reboot isby default a cold reboot. Thiscommand-lineoption changes back to theold default, a warm reboot. 

BOOT ARGUMENTS FOR SC SI DEVICES 

General notation forthissection: 

iobase— the first I/O port that the SCSI hostoccupies. Thesearespecified in hexadecimal notation and usually liein the 
rangefrom 0x200 to 0x3ff. 

irq— the hardware interrupt that the card is confi gured to use Valid valuesaredependent on the card in question but are 
usually 5, 7, 9, 10, 11, 12, and 15. The other values are usually used for common peripheralssuch asID E hard disks, floppies, 
serial ports, and so on. 

scsi - id — the I D that the host adapter usesto identify itself on the SCSI bus. Only somehost adaptersallow you to change 
thisvalue because most have it permanently specified internally. T he usuai default value is 7, but the Seagate and Future 
Domain TMC-950 boardsuse6. 

parity— whether the SCSI host adapter expeets the attached devices to supply a pari ty value with ali information exchanges. 
Specifying a 1 indicates parity checking isenabled, and ao disables parity checking. Again, notali adapters support selection 
of parity behavior asa boot argument. 
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max_scsi_luns=. . . 

A SCSI devicecan havea number of subdevi ces contai ned within itself. The most common exampleisoneof thenew SCSI 
CD-ROM sthat handle morethan onedisk at a ti me. Each CD isaddressed as a Logicai U nit N umber (LU N ) of that 
parti cular device M ost devices, such as hard disksand tapedrives, are onlyone device and areassigned to LU N 0. 

Some poorly designed SC SI devices cannot handle being probed for LU N s not equal to 0. T herefore, if the compi le- ti meflag 
config scsi multi lun is not set, newer kernels by default only probe LU N 0. 

To specify the number of probed LU N sat boot, oneentersmax scsi iuns=n asa boot arg, wheren is a number between 1 
and 8. To avoid problemsasdescribed, oneuses n=i to avoid upsetting such broken devices. 

SCSI TAPE CO NFIGU RATIO N 

Someboot-timeconfiguration of theSCSI tape driver can beachieved with thefollowing: 

st=b u f _s ze [,wri tet hreshol d [,max_bufs ]] 

The first two numbersarespecified in unitsof kilobytes. The default buf _s ze is 32KB, and the maximum size that can be 
specified isa ridiculous 16384KB. Thewrite_threshoid isthevalueat which the buffer iscommitted to tape with a default 
valueof 30KB. The maximum number of buffers vari es with the number of drives detected and has a default of two. A 
sampleusageis 

st=32,30,2 

Full details can befound i n the readme. st fi le that is in the scsi di rectoryof the kernel sourcetree. 

ADAPTEC AHA151X, AHA152X, AIC6260, AIC6360, SB16-SC SI CO NFIGU RATIO N 

T he ahanumbers referto cardsand the aie numbers referto the actual SCSI chipon thesetypesof cards, includi ng the 
SoundBlaster-16 SCSI. 

The probe code for these SCSI hostslooksfor an installed BIOS, and if noneispresent, the probe wi II notfind your card. 
Thenyou mustuseaboot arg oftheform: 

aha152x=i obase [,i rq [,scsi - i d [,reconnect [ ,pari ty ]]]] 

If the driver was compi led with debugging enabled, asixth valuecan be specified to set the debug leve!. 

Ali the parameters areasdescribed atthetop of thissection, and the reconnect vai ueallows device disconnect/reconnect if a 
nonzero value is used. A sample usage is asfollows 

aha152x=0x340,11 ,7,1 

N ote that the parameters must be specified in order, meaningthat if you want to specify a pari ty setti ng, then you must 
specify an i obase, i rq, scsi ■ i d, and reconnect valueaswell. 

ADAPTEC AH A154X CO NFIGU RATIO N 

Theahal542 seri es cards havean Ì82077 floppy controller on board, whereastheahal540 series cards do not. These are bus- 
mastering cardsand have parameters to set the "fairness" that isused to share the bus with other devices. The boot arg looks 
like thefollowing: 

aha1542=i obase[,bjson ,busoff [ , d ma s p e e d ] ] 

Valid i obase values are usuai ly oneof 0x130, 0x134, 0x230, 0x234, 0x330, or 0x334. Clone cards may permit other values. 

The bus on and bus off values refer to the number of microseconds that the card dominatesthelSA bus. Thedefaultsarenus 
on and 4us off so that other cards (such asan ISA LAN CE Ethernet card) have a chance to get access to the ISA bus 

Thedmaspeed value refersto the rate (in M B/s) at which the DM A (Direct M emory Access) transfers proceed. The default is 
5M B/s. N ewer revision cards allow you to select this value aspart of thesoft-configuration; older cards use jumpers. You can 
use values up to 10M B/s, assumi ng that your motherboard iscapableof handling it. Experi ment with caution if usi ng values 
over 5M B/s. 
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ADAPTEC AHA274X, AHA284X, AIC7XXX CO NFIGU RATIO N 

Theseboardscan accept an argument of the forni: 

aic7xxx=ext ended ,no_ r es et 

Theextended value, if nonzero, indicatesthat extended translati on for large disksis enabled. Theno_reset value, if nonzero, 
tei Is the driver notto reset the SCSI buswhen setti ng up the host adapter at boot. 

BUSLOGIC SCSI HOSTSCONFIGURATION (buslogÌC=) 

At present, thebuslogic driver acceptsonly one parameter, the I/O base. It expects that to beone of the following vali d 
values: 0x130, 0x134, 0x230, 0x234, 0x330, or 0x334. 

FUTURE DOMAIN TMC-8XX, TMC-950 CONFIGLI RATI 0 N 

If your card isnot detected at boottime, you must use a boot arg of theform 

tmc8xx=mem_ ba s e ,i r q 

The me m_ base value is the value of the memory-mapped I/O region that the card uses. Thisis usuai ly one of the following 

values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, Or0xde000. 

PRO AUDIO SPECTRUM CO NFIGU RATIO N 

ThePAS16 usesan NC5380 SCSI chip, and newer modelssupport jumperless configuration. The boot arg isof theform 

pas1 6=i 0 bas e ,i r q 

Theonly difference isthat you can specify an IRQ value of 255, which tei I s the driver to work without using interrupts, 
albeit at a performance loss. The 0 b a s e isusually 0x388. 

SEAGATE ST-OX CONFIGURATION 

If your card isnot detected at boottime, you must use a boot arg of theform 

st0x=mem_base , i r q 

T he me m. bas e value is the value of the memory-mapped I/O region that the card uses. Thisis usuai ly one of the following 

values: 0xc8000, 0xca000, 0xcc000, 0xce000, 0xdc000, Or0xde000. 

TRANTORT128 CONFIGURATION 

Thesecardsarealso based on theN CR5380 chip and accept the following options: 

t1 28=me tn_ b a s e ,i r q 

Thevalid values for me m_ bas e areasfollows: 0x1x000, 0x08000, 0xdc000, and 0xd8000. 

CARDSTHAT DON'T ACCEPT BOOT ARGS 

At present, the following SCSI cardsdo not makeuseof any boot-timeparameters. In somecases, you can hard-wi re values 
by di rectly editing the driver itself, if required. 

Always IN 2000, Adaptec ahal740, EATA-DMA, EATA-PIO, FutureDomain 16xx, N C R5380 (generic), N C R53c7xx to 
NCR53c8xx, Q logie, U Itrastor (includi ng u?4f), and Western Digital wd7000. 

HARD DISKS 

IDE DISK/CD-ROM DRIVER PARAMETERS 

T he I D E driver accepts a number of parameters, which rangefrom disk geometry specifications to support for broken 
controller chips. D rivespecific options are specified by using hdx= with x in a-h. 

N on-drive-specific options are specified with the prefix hd=. N otethat usi ng a dri ve-specific prefix for a non-drive-specific 
option will stili work, and theoption will just beapplied asexpected. 
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Also notethat hd= can beused to referto thenext unspecified drive in the (a, h) sequence. For thefollowing discussions, 
the hd= option will becited for brevity. SeethefileREADME.ide in nnux/drivers /block for moredetails. 

THEhd=cyls,heads,sects[ ,wpcom[ ,inq] ] OPTIONS 

Theseoptionsareused to specify the physi cai geometry of the disk. Only the first threevalues are required. The cylinder, 
head, and sectors valuesarethoseused by f disk. The write precorri pensati on valueisignored for ID E disks. The IRQ value 
specified is the IRQ used for the interface that the drive resideson and is not really adrive-specific parameter. 

THE hd=serialize OPTION 

Thedual IDE interface CM D-640 chip isbroken asdesigned such thatwhen driveson thesecondary interface are used at 
thesametimeasdriveson theprimary interface, it will corrupt your data. U si ng thi s option tei I s the driver to makesurethat 
both interfaces are never used atthesametime 

THE hd=dtc2278 OPTION 

This option tei Is the driver that you havea DTC-2278D IDE interface. The driver then triesto do DTC-specific operations 
to enablethesecond interface and to enablefaster transfer modes. 

THE hd=noprobe OPTION 

Do not probe for this drive. Thefollowing line 

hdb=noprobe hdb=1 166, 7, 1 7 

disables the probe but stili speci fies the drive geometry so that it is regi stered asa valid block device and henceusable. 
THE hd=nowerr OPTION 

Somedrivesapparently havethewRERR stat bit stuck on permanently. Thisenablesawork-around for these broken devices. 
THE hd=cdrom OPTION 

T his tells the I D E driver that thereisan ATAPI compati ble CD -ROM attached in place of anormal IDE hard disk. In most 
cases, theC D-ROM isidentified automati cai I y, but if it isn't, then thismight help. 

STAN D ARD ST-506 DISK D RIVER OPTIONS (hd=) 

The standard disk driver can accept geometry argumentsfor the disks si mi lar to thelD E driver. N ote however that it only 
expectsthreevalues(c/H/s); any more or any lessand it will silently ignoreyou. Also, it only acceptshd= asan argument; hda= 
and so on are not valid here. The format isasfollows: 

hd=c y I s , h e a d s , s e c t s 

If therearetwo disks installed, the precedi ng lineis repeated with the geometry parametersof thesecond disk. 

XT DISK DRIVER OPTIONS (xd=) 

If you areunfortunateenough to be usi ngoneof these old 8- bit cardsthat move data at awhopping 125KB/S, then hereis 
the scoop. If the card isnot recognized, you must use a boot arg of theform 

xd=t y pe , i r q ,i o ba s e ,d ma_ c ha n 

Thetype value specifies the particular manufacturer of the card, and you use oneof thefollowing: 0=generic, 1=DTC, 2, 3, 
4=Western D igital, 5, 6, 7=Seagate, or 8=0 M TI. The only difference between multi pie typesfrom the same manufacturer is 
the BIO S string used for detection, which isnot used if thetype is specified. 

Thexd_setupo function doesno checking on thevaluesand assumes that you entered ali four values. Don't disappoint it. 
HereisasampleusageforaWD1002 controller with the BIOS disabled orremoved, usi ng the default XT controller 
parameters: 

xd=2,5,0x320,3 
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CD-ROMS (NON-SCSI ATAPI. IDE) 

THE AZTECH INTERFACE 

Thesyntaxforthistypeof card is 

aztcd=i obase [,magi c number ] 

If you set the magi c_number to 0x79, the driver wi II run anyway in theevent of an unknown firmware versi on. Ali other values 
areignored. 

THE CDU-31A AND CDU-33A SONY INTERFACE 

ThisCD-RO M interface isfound on someof the Pro Audio Spectrum sound cardsand other Sony supplì ed interface cards. 
Thesyntaxisasfollows: 

cdu31a=i obase , [ i r q [ , is_ pas _ c a r d ] ] 

Specifyingan IRQ valueof a teli s the driver that hardware interruptsaren't supported (ason some PAS cards). If your card 
supportsinterrupts, you should usethem becausethey cut down on the CPU usageof the driver. 

Thei s. pas. card should beentered asPAs if usi ng a Pro Audio Spectrum card; otherwise, it should not bespecified at ali. 

THE CDU-535 SONY INTERFACE 

ThesyntaxforthisCD-ROM interfaceis 

sonycd535=i obase [ ,i r q ] 

A 0 can be used for the I/O base as a placeholder if you want to specify an I RQ value. 

THE GOLDSTAR INTERFACE 

ThesyntaxforthisCD-ROM interfaceis 

gsccH obase 

THE MITSUMI STANDARD INTERFACE 

ThesyntaxforthisCD-ROM interfaceis 

mcd=i obase , [i r q [ ,wai t _ vai uè ] ] 

The wa t _ v a i ne isused asan internai ti me-out value for peoplewho arehaving problemswith thei r drive and may or may 
notbeimplemented dependingon acompile-time#define.TheM itsumi FX400 isan IDE/ATAPI CD-ROM player and 
doesnotusethemcd driver. 

TH E M ITSU MI XA/MU LTISESSIO N IN TERFAC E (mcdx=) 

At present, this experi mental driver hasa setup function, but no parameters areimplemented (asof 1.3.15). Thisisfor the 
same hardware as previ ously described, but the driver has extended features. 

THE OPTICS STORAGE INTERFACE 

Thesyntaxforthistypeof card is 

optcd=i obase 

THE PHILLIPS CM 206 INTERFACE 

Thesyntaxforthistypeof card is 

cm206=[i obase ] [ ,i r q ] 

The driver assumesnumbers between 3 and 11 are IRQ values and numbersbetween 0x300 and 0x370 are I/O ports, so you 
can specify one, or both numbers, in any order. It also accepts cm206=auto to enable autoprobi ng. 
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THE SANYO INTERFACE 

Thesyntaxforthistypeof card is 

sj cd=i obase [ ,i r q [ ,dma_channel ] ] 

THE SOUNDBLASTER PRO INTERFACE 

Thesyntaxforthistypeof card is 

sbpcd=i obase ,type 

type isoneof thefollowing (case-sensitive) strings: SoundBlaster, LaserMate, or spea. The I/O baseisthat of theC D-ROM 
interface and not thatof the sound portion of the card. 

ETHERNET DEVICES 

D ifferent drivers use different parameters, but they ali at least sharehaving an IRQ, an I/O port basevalue, and a name In 
its most generic forni, it looks something like this: 

ether=i rq ,i obase [.parami [,param_2 , . . .paramS ]],name 

The first non-numeric argument istaken as the name. The para m_n values (if appi icable) usually have different meaningsfor 
each different card or driver. Typical param.n values are used to specify thingssuch asshared memory address, interface 
selection, DMA channel, and the like. 

The most common use of this parameter isto force probi ngfor a second ethercard because the default isto only probe for 

one. Thiscan beaccomplished with asimple 

ether=0,0,etb1 

Notethat the values of 0 fortheIRQ and I/O base in the exampletell thedriversto autoprobe. 

The Ethernet H owTo has extensi ve documentati on on using multi pie cards and on thecard-specific or driver-specific 
implementation of the para m_n values where used. Interested readers should refer to the section in that document on their 
parti cu lar card. 

THE FLOPPY DISK DRIVER 

T nere are many floppy driver options, and they areali listed in README.fd in unux/drivers/ block. This informati on istaken 
directly from that file. 

floppy=mask,allowed_drive_mask 

Setsthebitmask of allowed dri vesto mask. By default, only unitsO and 1 of each floppy controller areallowed. Thisisdone 
because certai n non-standard hardware (ASUS PCI motherboards) messup thekeyboard when accessi ng uni ts 2 or 3. This 
option issomewhat obsolete because of the cmos opti on. 

floppy=all drives 

Setsthebitmask of allowed drives to ali drives. U se this if you have more than two drives co nnected to a floppy controller. 

floppy=asus_pci 

Sets the bitmask to allow only units 0 and 1 (the default). 

floppy=daring 

Tel Is the floppy driver that you haveawell-behaved floppy controller. Thisallows more effi ci ent and smoother operati on but 
may fail on certai n controllers. Thiscan speed up certai n operations. 

floppy=0,daring 

T el Is the floppy driver that your floppy controller should beused with caution. 
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floppy=one_fdc 

T ells the floppy driver thatyou haveonly one floppy controller (default). 

f loppy=two_fdc OR f loppy=address, two_f de 

T ells the floppy driver thatyou havetwo floppy controllers. Thesecond floppy controller isassumed to Peat address. If 
addressisnot given, 0x370 isassumed. 

floppy=thinkpad 

T ells the floppy driver thatyou haveaThinkpad. Thinkpadsusean inverted convention for the disk changeline. 

f loppy=0, thinkpad 

T el ls the floppy driver that you don't have a T hi nkpad. 

floppy=drive,type,cmos 

Setsthecmos typeof drive to type. Additionally, thisdriveisallowed in thePitmask. Thisisuseful if you have more than two 
floppy drives (only two can PedescriPed in thephysical cmos), or if your BIOS uses non-standard cmos types. Setti ng the cmos 
to 0 for the first two drives (default) makes the floppy driver read thephysical cmos for th ose drives. 

f loppy=unexpected_intennupts 

Print awarning messagewhen an unexpected interrupt is received (default Pehavior) 

floppy=no unexpected_interrupts ORfloppy=L40SX 

Don't print a messagewhen an unexpected interrupt is received. Thisisneeded on IBM L40SX laptops in certain video 
modes. (Thereseemsto Pean interaction Petween video and floppy. The unexpected interruptsonly affect performance and 
can safely Peignored.) 

THE SOUND DRIVER 

Thesound driver can also accept Poot argsto overridethecompiled in values. Thisisnot recommended Pecause it israther 
complex. It isdescriPed in the Readme. Linux fi le in ìinux/drivers/ sound. It acceptsa Poot argof theform 

sound=de v i cel[,device2[,device3...[, deviceli]]] 

Eachdevi c e n value is of theformat 0xTa a a i d and thePytesareused asfollows: 
t— device type i=fm, 2=sb, 3=pas, 4=gus, 5=mpu4bi, 6=sbi6, and 7=sbi6-mpu40i 
aaa— I/O addressin hex 
— interrupt line in hex(i0^a, n=b, ... ) 
d— DMA channel 

Asyou can see, it getspretty messy, and you arePetter off to compile in your own personal values as recommended. U singa 
Poot arg of sound=a disaPlesthe sound driver entirely. 

THE BUS MOUSE DRIVER (bmouse=) 

ThePusmousedriveronlyacceptsoneparameter, the hardware IRQ value to Peused. 

AUTHORS 

LinusTorvalds(and many others) 

SEE ALSO 

klogd(8), lilo.conf(5), lilo(8), mount(8), rdev(8) 

Thisman pagewasderived from theBootParameterHOWTO (version 1.0.1) written PyPaul Gortmaker. Moreinforma- 
tion can Pefound in this (or a more recent) HOWTO. 

Linux 1.3.19, 15 August 1995 
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grof f_me 

groff_me— troff macros for formatti ng papers. 
SYNOPSIS 

groffjne [ opti o n s ] file ... 
troffjne [ opti o n s ] file ... 

DESCRIVO N 

Thismanual page describes the GN U version ofthe me macros, which is part ofthe grof f documentformatting system. 
This version can beused with both GNU troff and U N IX troff. This package of troff macro defi nitions provides a canned 
formatti ng facility for technical papers in variousformats. 

Themacro requests are defi ned asfollows. M any troff requestsareunsafein conjunction with this package; however, these 
requestscan beused with impunity after the first .pp: 



.bp Beginnewpage 

.br Break output line here 

.sp (i Insertn spacinglines 

.is n Linespacing; n =1 single, n =2 doublé space 

.na Noalignmentof rightmargin 

.ce n Center next n lines 

.ui n Underlinenextn lines 



Output ofthe pie, eqn, refer, and tbi preprocessors is acceptable as input. 
FILES 

/usr/lib/groff /tmac/tmac.e 

SEEALSO 

groff(l), gtroff(l), _me Reference M anual, Eric P. Al Iman, W riti ng Papers with Groff Using_me 
REQUESTS 

This list is incomplete seethe me Reference M anual for interesting details. 



Request 


Initial Value 


Cause Break 


Explanation 


.(e 




Yes 


Begin centered block. 


.(d 




No 


Begin delayed text. 


.(f 




No 


Begin footnote. 


.(i 




Yes 


Begin list. 


■(q 




Yes 


Begin major quote. 


.(XX 




No 


Begin indexed item in indexx. 


■ (z 




No 


Begin floating keep. 


■ )o 




Yes 


End centered block. 


.)d 




Yes 


End delayed text. 


• )f 




Yes 


End footnote. 


• )1 




Yes 


End list. 


■)q 




Yes 


End major quote 



continues 
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Request I nitial Value Cause Break 

7^ - Yes 

.)z - Yes 

.++ m H - NO 



.+c t - Yes 

.ic 1 Yes 

.2c 1 Yes 

. en - Yes 

. EQ x y - Yes 

.ge - Yes 

.gs - Yes 

.pe - Yes 

.ps - Yes 

.te - Yes 

.th - Yes 

.ts x - Yes 

.bi No No 

.ba +n 0 Yes 

.oc No Yes 

.bi x No No 

.bu - Yes 

.bx i No No 

. ef 1 x 1 y 1 z 1 " " No 

.eh ' x 1 y ' z "" N 0 

. f o ' x ' y ' z "" No 

.hx - NO 

.he ' x ' y ' z 1 "" N 0 

.hi - Yes 

.ii No No 

.ip x y No Yes 



Explanation 

End index item. 
End floating keep. 
Definepapersection. 

m definesthepart ofthepaper and can bec 
(chapter), a (appendix), p (preliminary, such as 
abstract, tableof contents, and so on), b (bibliogra- 
phy), rc (chapters renumbered from page one each 
chapter), or ra (appendix renumbered from page 
one). 

Begin chapter (or appendix and so on asset by .++). 
T is the chapter ti ti e. 

0 ne column format on a new page. 

Two column format. Equation number isy. 

Space after equation produced byeqn orneqn. 

Precede equation; break out and add space. 

Theoptional argumentx may be i to indent 
equation (default), l to left-adjust the equation, ore 
to center the equation. 

End gremlin picture. 

Begin gremlin picture. 
End pie picture. 
Begin pie picture. 
End table 

End headingsection of table. 

Begin table; if x ìsh, table has repeated heading. 

Printx in boldface; if no argument switch to 
boldface. 

Augments the base indent by n. 

This indent isused to settheindenton regulartext 

(like paragraphs). 

Begin new column. 

Printx in bold italics (no fili only). 

Begin bulleted paragraph. 

Printx in a box (no fili only). 

Set even footer to x y z . 

Set even header to x y z . 

Set footer tox y z. 

Suppress headersand footerson next page. 

Set header to x y z . 

Draw ahorizontal line. 

I tal i cize x ; if x ismissing, italic text follows. 

Start indented paragraph with hanging tag x . 
Indentation is y ens (default is 5). 
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Request 


1 nitial Value 


Causs Break 


Explanation 


■ ip 


Yes 


Yes 


Start left-blocked paragraph. 


.np 


1 


Yes 


Start numbered paragraph. 


.of ' x ' y ' z ' 




No 


Set odd footer to x y z . 


.oh 'x 'y 'z 




No 


Set odd header to x y z . 


.pd 


_ 


Yes 


Printdelayed text. 


■PP 


No 


Yes 


Begin paragraph. First line indented. 


. r 


Yes 


No 


Roman textfollows. 


. re 




No 


Reset tabs to default values. 


.sh n x 


_ 


Yes 


Section head follows; font isautomatically bold. n is 
level of section. x istitleof section. 


.sk 


No 


No 


Leave the next page blank. 0 nly one page is 
remembered ahead. 


.sm x 




No 


Setx in asmaller pointsize 


.sz +n 


lOp 


No 


Augmentthepointsizeby n points. 


■tp 


No 


Yes 


Begin ti ti e page. 


.U X 




No 


U nderlineargument (even in troff) (nofill only). 


.uh 




Yes 


Like .sh but unnumbered. 


.xp X 




No 


Print indexx. 



GroffVersion 1.09, 6 August 1992 
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grof f_mm— groff mm macrOS. 

SYNOPSIS 

groffjngm [ opti ons ... ] [f il es . . . ] 

D ESC RIPTIO N 

Thegroff mm macros are intended to becompatiblewith theDWB mm macroswith thefollowing limitations: 
N o letter macros are implemented (yet). 
N o Bell Labs localisms are implemented. 
The macros ok and pm are not implemented. 
groff mm does not support cut marks. 

mgm is intended to be internati onal. Therefore, it is possi bleto write short national macro-fi lesthat changeall English text to 
thepreferred language Usemgmse asan example. 

groff mm hasseveral extensions: 

ic [1] Begin onecolumn processing. A 1 asargument disables the page break. 

app name text Begi n an appendix with the name n a me . Automatic naming occurs if name is ■ ■ . T he 

appendixesstartswith A if auto isused. A new page is ejected, and a header isalso 
produced if the number vari able Aph is non-zero. T his is the default. T he appendix 
always appear in the I ist of contentswith thecorrect page number. The name 
appendix can bechanged by setti ng the stri ng App to the desi red text. 
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APPSK name pages t ext 

B1 
B2 
BVL 

COVER [a r g ] 



COVEND 

GETHN r e f n a me [var name ] 
GETPN r e f n a me [var name ] 
GETR r ef name 

GETST r ef name [var name ] 
INITR fi I e n a me 



MC c o I u mn - s i z e [col umn- separat i on ] 
MT [ar g [addr ess ee ] ] 



MOVE y- pos [x- pos [I i ne- 1 engt h ] ] 



Sameas .app, but the page num ber isincremented with pages . Thisisused 
when diagramsor other non-formatted documents areincluded as appen- 
di xes. 

Begin box(asthems macro) Drawsabox around thetext. 
End box. Finish the box. 

Start of broken vari able-item list. LikevL buttextbeginsalwaysatthenext 
line. 

cover beginsacoversheetdefinition. It isimportantthat .cover appears 
beforeany normal text. .cover usesarg to build thefilename/usr/iib/groff/ 
tmac/mm/arg.cov. Therefore, it ispossibleto create unlimited typesof 
coversheets. ms.cov issupposed to look likethe ms coversheet. .cover requires 
a .covend attheend of thecover definition. Always usethisorderof thecover 
macros: 

.COVER 

.TL 

.AF 

.AU 

.AT 

.AS 

.AE 

.COVEND 

H owever, only .tl and .au arerequired. 

Thisfinishes thecover description and prints the cover page. It isdefined in 
the cover fi le. 

Includestheheader number wherethecorrespondingsETR ref name was 
placed. Will bex.x.x. in passi. See initr. If var name isused, gethn setsthe 
string variablevarname to theheader number. 

I ncludes the page number where the correspondi ng setr ref n a me was placed. 
Will be9999 in passi. See initr. If «amarne isused, getpn setsthe string 
variablevarname to the page number. 

C ombines gethn and getpn with thetext 'chapter' and 1 , page 1 . The string 

Qrf contai ns the text for reference: .ds Orf See chapter \\*[Qrfh], page 

\\*[Qrf p ]. Qrf may be changed to support other languages. Stri ngs Qr f h and 
Qrf p are set by getr and contai n the page and header number. 
I ncludes the string saved with thesecond argument to .setr. Will bedummy 
stringin passi. I f v a r n a me isused, getst setsthestring variablevarname tothe 
saved string. See initr. 

I nitialize the reference macros. Referenceswill be written to f i i ename . tmp 
and f i i ename .qrf. Requirestwo passeswith groff. The first looksfor 
references and thesecond includesthem. initr can beused several times, but 
it is only the first occurrenceof initr that isactive. Seealso setr, getpn, and 
gethn. 

Begin multiple columns. Return to normal with ic 

M emorandum type. Thearg ispart of afilenamein /usr/iib/groff/tmac/mm/ 

*.mt. M emorandum typea through 5 aresupported, includi ng 5 1 r i ng. 

addressee just sets a variable, used in the AT&T macros. 

M oveto a position, page offset set to x-pos. Ifiine-iength isnot given, the 

difference between the current and new page offset is used. U se pgform 

without argumentsto return to normal. 
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MULB cwl spacel [cw2 s p a c e 2 [cw3 . . . ] ] 



MULN 
MULE 

PGFORM [I i nel engt h [ p a g e I engt h [pageof f s et [1]]]] 
i nel engt h , pagel engt ti and/or pageof f set. 



PGNH 



SETR r ef na me [stringi 



TAB 



VERBON [fi ag [poi ntsi ze [font ]]] 



Begin a special multi-column mode. Every column'swidth must 
bespecified. Also, the space between the columns must be 
specified. Thelast column does not need any space definiti on. 
mulb starts a diversi on and mule endsthediversion and printsthe 
columns. The unit for width and space isn, but mulb acceptsall 
normal unitspecificationssuch asc and i. mulb operatesin a 
separate en vi ronment. 

Begin the next column. Thisistheonly wayto switch columns 
End the multi-column modeand printthecolumns. 
Thismacro can beused for special formatting, such as pgform 
letterheads. Sets can be used without arguments to reset 
everyth i n g after a move . A I i n e break i s do ne u n I ess th e f ou rth 
argument isgiven. Thiscan beused to avoid the pagenumber 
on the first page while setting new width and length. 
N o header isprinted on the next page. Used to get rid of the 
header in letters or other special texts. Thismacro must beused 
before any text to inhibit the page header on the first page. 
Remember thecurrent header and pagenumber asref name. Saves 
stri ng if st ri ng isdefined. st ri ng isretrieved with .getst. See 

INITR. 

Reset tabsto every 5n. Usuallyusedto reset any previ oustab 
positions. 

Begin verbatim output usi ng Courier font. Usually for printing 
programs. Ali characters haveequal width. The pointsize can be 
changed with thesecond argument. By specifying thefont 
argument, it is possi bleto use an other font instead of Courier. 
f i ag controis several special features. It contai ns the sum of ali 
wanted features: 



Value 



D escri pti on 



1 D isable the escape- eh aracter (n). T his is usually 
turned on during verbose output. 

2 Add an empty line before the verbose text. 

4 Add an empty li ne after the verbose text. 

8 Printtheverbosetextwith numbered lines. This 

addsfour digit-sized spacesin thebeginningof 
each line. Finer control isavailablewith the 
string-variableverbnm. It contai ns ali arguments 
to thetroff-command .™, usually 1. 

16 Indent the verbose text with fivens. This is 

controlied by thenumber-variableverbin (in 
units). 



VERBOFF 

Newvariablesinmgm: 

App 
Aph 



End verbatim output. 



A stri ng containing the word appendix. 

Print an appendix page for every new appendix if this number 

variableis nonzero. No output will occurifAph iszero, butthere 
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will alwaysbean appendix entry in the list of contente 

Hps N umber variablewith theheading pre- space leve!. If theheading 

level is lessthan or equal to Hps, then two lines precede the section 
heading instead of one. D efault is first level only. Thereal amount 
of lines is controlied by the vari ablesHpsi and Hps2. 

Hpsi This isthe number of lines preceding .Hwhen the heading level is 

greater than Hps. Valueisin units, usually e.sv. 

Hps2 This isthe number of lines preceding .Hwhen the heading level is 

lessthan or equal to Hps. Valueisin units, usually iv. 

Lifg String containing figure. 

Litb String containing table. 

Liex String containing exhibit. 

Liec String containing equation. 

neon String containing contents. 

Lsp Thesizeof an empty line. Usually 0.5v, but itisi v if n isset 

(.nroff). 

moi - M012 Stri ngs contai ni ng J anuary to December. 

Qrf String Containing "See chapter \\*[Qrfh], page \\n[Qrfp].". 

pgps Controls whether header and footer point sizeshould follow the 



current setti ng or just changewhen the header and footer is 
defined. 

Value Description 

0 Pointsizewill onlychangetothecurrentsetting 
when .ph, .pf, .oh, .eh, .of, or .oe isexecuted. 

1 Pointsizewill change after every .s. This isthe 
default. 



Sectf 



Sectp 



.mgm 



Flag control li ng section figures. A nonzero value enables this. See 
also register N . 

Flag controlling section pagenumbers. A nonzero value enables 

this. See also register N . 

Alwaysl. 



A filecalled locale or iang_iocaie isread after the initiation of theglobal variables. It istherefore possi bleto localizethe 
macroswith a company nameand so on. 



T he following standard macrosareimplemented: 

20 
AE 

AF [ n a me o f f i r m ] 

AL [type [t ext - i ndent [1]]]] 

AS [ a r g [i ndent ]] 

AST [t i 1 1 e ] 

AT t i 1 1 e 1 [ti ti e 2 . . . ] 

Al) name [i ni t i al s [I oc [dept 

B [boi d-text [prev-font-text [...]]] 



Begin two column processing. 

Abstract end. 

Author'sfirm. 

Start autoincrementlist. 

Abstract start. I ndent isspecified in ens, but scali ng isallowed. 

Abstract ti ti e. D efault is 'abstract 1 . 

Author'stitle. 

[ext [r oom [a r g [a r g 

[arg]]]]]]]] Author information. 

Begin boldface. Nolimiton the number ofarguments. 
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BE 

BI [b o I d-text [italic-text [bold-text [. 

BL [ t e x t - i ndent [1]] 

BR [bold-text [roman-text [boi d-text [.. 

BS 

DE 

DF[f o r ma t [fili [ri ndent ] ] ] 

DL [t ext ■ i ndent [1 ] ] 

DS [format [fili [ri ndent ]]] 

EC [t i 1 1 e [over r i de [f I ag [r ef na me ] ] ] ] 

EF [arg] 

EH [arg ] 
EN 

EQ [I a be ] 

EX [t i 1 1 e [over r i de [f I ag [r ef name ] ] ] ] 

FD [arg [1]] 
FE 

FG [t i 1 1 e [over r i de [f I ag [r ef name ] ] ] ] 
FS 

H level [headi ng-text [headi ng-suffi x]] 

HC [hyphenati on-character ] 

HM [argl [a r g 2 [ . . . [ a r g 7 ] ] ] ] 

HU headi ng-text 

HX di ève r I ève headi ng-text 

HY di ève r I ève headi ng-text 

HZdlevel rlevel headi ng-text 

I [italic-text. 



IB [itali e-text 



End bottoni block. 
. . 1 1 1 Bold italic. N o limit on the number of arguments. 

Start bullet list. 

. IH Bold roman. N o limit on the number of arguments. 

Bottom block start. 
Display end. 

Begin floating display (no nesting allowed). 
Dash list start. 

Static display start. Can now haveunlimited nesting. Also, right- 
adjusted text and block may beused (r or rb as format). 
Equation title. If r ef name isused, then theequation number is 
savedwith .setr and can beretrieved with .getst ref name. 
Even pagefooter. 
Even pageheader. 
Equation end. 
Equation start. 

Exhi bit title. If ref name isused, then the exhi bit number issaved 
with .setr and can beretrieved with .getst ref name. 
Footnotedefault format. 
Footnoteend. 

Figure title. If ref name isused, then the figure number issaved 

with .setr and can beretrieved with .getst ref name. 

Footnote start. Footnotesin displaysisnow possible. 

N umbered heading. 

Set hyphenati on character. 

H eading mark style. 

Unnumbered header. 

U ser-defined headi ng exit. C alled just before pri nting the header. 
U ser-defined headi ng exit. C alled just before pri nti ng the header. 
U ser-defined heading exit. C alled just after pri nting the header. 



IR [itali c - 1 ext 



LB t ext • i nd e nt ma r k- i ndent 



LC [list I evel ] 
LE 

LI [mark [1]] 

ML mar k [t ext ■ I ndent ] 

MT [arg [addr ess ee ] ] 



[pr e v- f o nt ■ t ex t 
[italic-text [...]]] 



Italie. 



[boi d-text 
[italic-text 



[...]]] Italie bold. 



[ r o ma n ■ t e x t 

[italic-text [...]]] Italie roman. 

pad type [mark 

[Li-space [LB-space]]] List begin macro. 

List status ci ear. 

List end. 

List item. 

M arked list start. 

M emorandum type. See above note about mt. 
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ND new- dat e 
OF [a r g ] 
OH [arj] 
OP 

P [type ] 
PE 

PF [arj] 

PH [ars] 

PS 

PX 

R 

RB [r orna n- 1 ext [boi d-text 

RD [prompt [di versi on [stri ng]]] 
RF 

RI [r o ma n - 1 e x t 

RL [t ext ■ i ndent [1 ] ] 
RP [ a r g [ars]] 
RS [stri ng-rame] 
S [s i z e [spaci ng]] 



SA [arg ] 
SK [pages ] 

SM st r i ngl [st r i n g 2 [stri ng3]] 
SP [i i nes ] 

TB [t i 1 1 e [over r i de [f I ag [ r e f n a me ] ] ] ] 
TC [si evel [spaci ng 



TE 

TH [N] 
TL 

TM [numi [num2 [...]]] 
TP 

TS [H] 

TX 

TY 



N ew date 

0 dd page footer. 

Odd pageheader. 

Ski p to odd page. 

Begin new paragraph. 

Pictureend. 

Page footer. 

Pageheader. 

Picture start (from pie). 

Pageheader user-defi ned exit. 

Roman. 

[roman-text [...]]] Roman-DOld. 

Read to di ver s i on and/or s t r i n g . 
Referenceend. 

[i tal i c-text 

[roman-text [...]]] Roman italic. 

Reference list start. 
Producereferencepage. 
Reference start. 

Set pointsizeand verti cai spaci ng. If any argument equalsp, then the 

previ ousvalueisused. A c meanscurrent value, and d means default 

value. If + or - isused befo re the value, an incrementor decrement of 

the current value isdone. 

Set adjustment. 

Ski p pages. 

M akea stri ng smaller. 

Space verti cai ly. i i nes can have any scali ngfactor, such as3i or 8v. 
Table title. If ref name isused, then thetablenumber issaved with 
.sETRandcan beretrieved with .getst ref name. 

[tlevel [tab [hi [h2 
[ h 3 [h4 [h5]]]]]]]]] 

Tableof contents. Ali textscan beredefined. new stri ng vari ables 

Lifg, Litb, Liex, Liec, and Licori COntain "Figure", "TABLE", "Exhibit", 

"Equation", and "contents" . T hese can beredefined to other 

languages. 

Tableend. 

Table header. 

Begin titleof memorandum. 

Technical memorandum numbersused in .mt. U nlimited number of 
arguments may be given. 

Top of page user-defi ned macro. N otethat header and footer is 
printed in a separate environment. Line length ispreserved. 
Tabi e start. 

User-defined tableof contents exit. 

U ser-defined table of contents exit (no "contents"). 



VL [t ext ■ i ndent [mar k- i ndent [1 ] ] ] 
VM [top [bottoni]] 
WC [f or mat ] 

Strings used in mgm: 

EM 
HF 

HP 

Lf 
Lt 
Lx 
Le 
Rp 
Tm 

Number vari ables used in mgm: 

Cl=2 
Cp=0 

D=a 

De=0 

Df=5 

Ds=1 

Ej=0 

Eq=0 

Fs=1 

H1 - H7 

Hb=2 

Hc=0 

Hi=1 

Hs=2 
Ht=0 
Hu=2 
Hy=1 

Lf =1 , Lt=1, Lx=1, Le=0 

Li=6 
Ls=99 

N=0 
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Variable-item list start. 
V erti cai margin. 

Footnoteand display width control. 
Em dash stri ng. 

Font list forheadings, usually "2 22222 2 11 . Nonnumericfont 
namesmay al so be used. 

Point size list for headings. Usually "0 0 0 0 0 0 0", which isthe 

sameas"i0 10 10 10 10 10 10". 

Contains"LisT of figures". 

Contains"LisT of tables". 

Contains "list of exhibits". 

Contains n LisT of equations". 

Contains "REFERENCES". 

Contains \(tm, trademark. 

Contents level [0:7]; contents saved if heading leve! <=ci. 

Ejectpagebetween list of xxxx if cp == 0. 

D ebug f lag, values greater than 0 produce varyi ng degree of debug. A 

valueof 1 gives information about the progress of formatting. 

Eject after floating display isoutput [0:1]. 

Floating keep output [0:5]. 

Space before and after display if =1 [0:1]. 

Eject page. 

Equation label adjust 0=left, 1 =ri ght. 

Footnote spaci ng. 

H eading counters. 

H eading break level [0:7]. 

H eading centering level [0:7]. 

H eading temporary indent [0:2]. 0 isno indent, left margin. 1 is 
i ndent to right, like .p 1.2 isi ndent to lineup with text part of 
precedi ng heading. 
Heading space level [0:7] 

H eading numbering typeo is multiple (1.1.1 ... ). 1 is single. 
Unnumbered heading level. 

Hyphenation in body. 0 isno hyphenation. 1 ishyphenation 14 on. 
E nables (1 ) or disables (0) the printi ng of a list of figures, list of tables, 
list of exhibits, and list of equations. 
List indent, used by .al. 

List space, if current list level isgreaterthan ls, then no spaci ng 
occursaround lists. 
N umbering style [0:5]: 

0 =(D efault) N ormai header for ali pages. 

1 = H eader replaces footer on first page; header is empty. 

2 =Page header is removed on the first page. 



1234 
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3=Section page num beri ngenabl ed. 

4 =Page header is removed on the first page. 

5 =Section page and section figure numberingenabled. Seealso the 
number register sectf and sectp. 

Np=0 N umbered paragraphs. 0 is not numbered. 1 is numbered in first-level 

headings. 

of=e Format of figure, table, exhibit, and equation titles. 0 is 11 . 11 . 1 is 

p Current page number, usuai ly the sameas% unlesssection-page 

numbering isenabled. 
pì=5 Paragraph indent. 

ps=i Paragraph spaci ng. 

pt=0 Paragraph type. 0 is left-j ustifi ed. 1 isindented .p. 2 isindented .p 

except after .h, .de, or .le. 
sì=5 D i splay indent. 

AUTHOR 

Jorgen Hagg, Lund Insti tute of Technology, Sweden (jhiefd.ith.se). 
FILES 

/usr/lib/grof f /tmac/tmac. gm 
/usr/lib/grof f /tmac/mm/* .cov 
/usr/lib/grof f/ tmac/mm/ *.MT 
/usr/lib/grof f / tmac/mm/ locale 

SEEALSO 

groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), mm(7), mgmse(7) 

G roff Version 1.09, 14 February 1994 

grof f_ms 

grof f_ms— grof f ms macrOS. 

SYNOPSIS 

groff_mgs [ opti ons . . . ] [f il es . . . ] 

D ESC RIPTIO N 

Thismanual page describes the GN U version of thems macros, which ispart of the grof f document formatti ng system. The 
groff ms macros are i ntended to becompatiblewith thedocumented behaviorof the4.3 BSD U N IX ms macros, subjectto 
thefollowing limitations: 

T he internalsof groff ms arenotsimilarto the internals of U N IX ms, so documentsthat depend upon implementation 
detai Is of U N IX ms might not work with groff ms. 

There isno support for typewriter-like devices. 

Berkeley locai isms, in particular the tm and ct macros, are not implemented. 

groff ms does not provide cut marks. 

M ulti pie I i ne spaci ng isnot allowed. (U se a I arger verti cai spacing instead.) 
groff ms does notwork in compati bility mode (such aswith the -c option). 



groff ms 



Theerror-handling policyof groff ms isto detect and report errors, rather than silently ignorethem. 

The groff ms macros use many features of G N U troff and thereforecannot beused with any other troff. 

Bell Labs localisms are not implemented in either the BSD ms macros or in the groff ms macros. 

SomeU N IX ms documentati on saysthatthecwand gw number registerscan beused to control thecolumn width and gutter 
width. This is not the case. T hese number registers are not used in groff ms. 

M acrosthat cause a reset set the indent. M acrosthat changethe indent do not increment or decrement the indent, but rather 
set it absolutely. Thiscan cause problemsfor documentsthat define additional macros of the r own. The solution isto not 
use the in request but instead to use the rs and re macros. 

The number register gs i s set to 1 by the groff ms macros but is not used by theLI N IX ms macros. It isintended that 
documentsthat need to determi ne whetherthey arebeingformatted with U N IX ms or groff ms use this number register. 

Footnotes are implemented so that they can safely beused within keepsand displays. Automati cally numbered footnotes 
within floating keepsarenot recommended. It issafeto haveanother \«* between a \** and thecorresponding .fs; it is 
required only that each .fs occur after thecorresponding \** and that the occurrencesof .fs are in thesameorder asthe 
corresponding occurrences of \**. 

Thestrings \*{ and \*> can beused to begin and end asuperscript. 

SomeU N IX V10 ms features are implemented. The b, i, and bi macros can havean optional third argument that isprinted 
in the current font before the first argument. Thereis a macro cw li ke b that changesto aconstant-width font. 

Thefollowing stringscan beredefined to adapt thegroff ms macros to languages other than English: 



String 


Default Value 


REFERENCES 


Ref erences 


ABSTRACT 


ABSTRACT 


TOC 


Table of Contents 


M0NTH1 


January 


M0NTH2 


February 


M0NTH3 


March 


M0NTH4 


Aprii 


M0NTH5 


May 


M0NTH6 


June 


M0NTH7 


July 


M0NTH8 


August 


M0NTH9 


September 


MONTH10 


October 


M0NTH1 1 


November 


M0NTH12 


December 



The font fami ly i s reset from the string fam; at initialization if this string isundefined, it is set to the current font family. The 
pointsize, verti cai spacing, and inter-paragraph spaci ngfor footnotes are taken from the number registers fps, fvs, and fpd; 
at initialization, these are set to \n(Ps-2, \n[FPS]+2, and \n(PD/2; however, if any of these regi sterswas defined before 
initialization, it is not set. Thehyphenation flags (as set by the .hy request) are set from theHY register; if this was not defined 
at initialization, itis setto 14. 

Right-aligned displays are available with .ds r and .rd. 

Thefollowing conventions are used for namesof macros, strings, and number registers. External names available to 
documentsthat use the groff ms macroscontain only uppercase letters and digits. Internally, the macros are divided into 
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modules. N amesused only within onemoduleareof theform modui e *na me . N amesused outsidethemodulein which they 
are defined are of theform ™ d u i e @n a me . N ames associ ated with a parti cular environment are of theform env ronment mane; 
theseareused only within the par module, and name doesnot havea moduleprefix. Constructed namesused to implement 
arrays are of theform array n ndex. Thus, thegroff ms macros reserve the following names: 

N ames contai ni ng* 
N ames contai ni ng e 
N ames contai ni ng : 

N ames contai ni ng only uppercase letters and digits 
FILES 

/usr/lib/groff /tmac/tmac.gs 

SEEALSO 

groff(l), gtroff (1), gtbl(l), gpic(l), geqn(l), ms{7) 

Groff Version 1.09, 9 January 1994 



hier 

mer— Description of thefilesystem hierarchy. 
D ESC RIPTIO N 

A typical Linux system has, amongothers, thefollowingdirectories: 

/ This istheroot directory. Thisiswherethewholetreestarts 

/bin This directory contai nsexecutableprogramsthat are needed in single-user mode and to 

bri ng the system up or repai r it. 
/boot C ontains stati c fi les for the boot loader. This directory only holds the fi les that are 

needed during the boot process. Themap installer and confi guration filesshould go to / 

sbin and lete. 

/dev Special or device fi les that referto physical devices. Seemknod(l). 

/dos If both M S-DOS and Linux arerun on one computer, thisis a typical place to mount a 

DOSfilesystem. 

lete C ontains configurati on files that are locai to the machine. Somelarger software 

packages, such asXll, can havetheirown subdirectoriesbelow lete. Site-wide 
confi guration files may beplaced hereor in /usr/etc. N evertheless, programsshould 
always look for these fi les i n lete and you may have links for these fi lesto /usr/etc. 

/etc/skei When a new user account iscreated, files from this directory are usuai ly copi ed into the 

user's home directory. 

/etc/xn Configuration filesfortheXllwindow system. 

/home On machineswith homedirectoriesfor users, these are usuai ly beneath this directory, 

directly or not. The structureof this directory dependson locai administration 
decisions. 

/iib This directory should hold thoseshared libraries that are necessaryto bootthesystem 

and to run thecommandsin theroot filesystem. 
/mnt This is a mount point for temporarily mounted filesystems. 

/proc Thisisamount pointfortheproc filesystem, which providesinformation about 

running processesand the kernel. This pseudo-fi lesystem isdescribed in moredetail in 

proc(5). 



/sbin 

/tmp 

/usr 

/usr/X11R6 
/usr/X11R6/bin 

/usr/X11R6/lib 
/usr/X11R6/lib/X11 

/usr/X11R6/include/X11 

/usr/bin 

/usr/bin/X11 

/usr/dict 
/usr/etc 

/usr/include 
/usr/include/X11 

/usr/include/asm 

/usr/include/linux 



/usr/include/g++ 
/usr/lib 

/usr/lib/X11 

/usr/lib/gcc -lib 

/usr/lib/groff 

/usr/lib/uucp 

/usr/lib/zoneinf o 

/usr/local 

/usr/local/bin 

/usr/local/doc 

/usr/local/etc 

/usr/local/lib 

/usr/local/info 

/usr/local/man 

/usr/local/sbin 



Like /bin, this directory holdscommandsneeded to boot the system but usually not 
executed by normal users. 

T his directory contai nstemporary files that may be deleted with nonotice, such asbya 
regularjob or at system bootup. 

Thisdirectory isusually mounted from a separate partition. It should hold only 
sharable, read-only data so that itcan be mounted by variousmachinesrunning Linux. 
TheX window system, versi on 11, release6. 

Binariesthat belongto theX window system; often, thereisasymbolic link from the 

moretraditional /usr/bin/xn to here. 

Data files associ ated with theX window system. 

These contai n mi scellaneous files needed to run X; Often, thereisasymbolic link from 
/usr/iib/xn to thisdirectory. 

Contains include files needed for compi li ng programsusingtheXll window system. 
Often, thereisasymbolic link from /usr/inciude/xn to thisdirectory. 
This is the primary directory for executableprograms. M ost programs executed by 
normal users that are not needed for booti ng or for repai ri ng the system and that are not 
installed locai ly should beplaced in thisdirectory. 

This is the tradì ti onal place to look for X 11 executables; on Linux, it usually isa 

SymboliC link tO /usr/X11R6/bin. 

Thisdirectory holds files contai ni ng word listsfor speli -eh eckers. 
Site-wi de configurati on fi lesto beshared between several machinesmay bestored in this 
directory. However, commands should always referencethose files usingthe/etc 
directory. Links from filesin /etc should pointto the appropriate files in /usr/etc. 
IncludefilesfortheC compiler. 

I nclude files for the C compiler and theX window system. T his isusually a symbolic 

link tO /usr/X11R6/include/X11. 

Include files that declare some assembler functions. This should bea symbolic link to/ 

usr /sre/ linux /include /asm. 

This contains information that may change from system releaseto system releaseand 
should bea symbolic link to /usr/src/iinux/inciude/iinux to get at operati ng-system- 
specific information. 

Includereste use with theGN U C++ compiler. 

Object libraries, includi ng dynamic libraries, plus some executables that usually are not 

invoked directly. M orecomplicated programsmay havewholesubdirectoriesthere. 

The usuai place for data files associ ated with X programs and configuration files for the 

X system itsdf. On Linux, it usually isa symbolic link to /usr/xnR6/iib/xn. 

Contains executables and include filesfortheG N U C compiler, gcc(l). 

Files for theGN U grott documentformatting system. 

Files for uucp(l). 

Files for ti me zone information. 

This iswhere programs that are locai to the site typically go. 

Binari es for programslocal to the site go there. 

Locai documentation. 

Configuration files associated with locally installed programs go there. 
Files associated with locally installed programs go there. 
Info pages associated with locally installed programsgo there. 
M an pages associ ated with locally installed programsgo there. 
Locally installed programs for system administration. 
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/usr/local/src 
/usr/man 

/usr/man/cat[ 1 -9] 

/usr/man/l oca I e /man[1 -9] 

/usr/sbin 

/usr/src 
/usr/src/linux 
/usr/tmp 
/var 

/var/adm 
/var/lock 



/var/log 

/var/preserve 

/var/run 

/var/spool 

/var/spool/at 

/var/spool/cron 

/var/spool/lpd 

/var/spool/mail 

/var/spool/smail 

/var/spool/news 

/var/spool/uucp 

/var/tmp 



Source codefor locai ly i nstalled software. 

M an pagesgo in thereinto their subdirectories. 

T hese directories contain preformatted manual pages accordi ngto their man page 
section. 

These directories contain manual pages that are in source code form. Systems that use a 

uniquelanguageand code set forali manual pages may omitthe ocai e substring. 

This directory contai ns program binariesfor system administration that are notessential 

fortheboot process, for mounting /usr, or for system repair. 

Sou ree f i I es f o r di ff eren t parts of th e system . 

This contains the sourcesfor the kernel of the operati ng system itself. 

An alternative placete storetemporary files; This should bea link to /var/tmp. 

T his di rectory contains fi les that may change in size, such as spool and log files. 

This directory issuperseded by /var/iog and should beasymbolic linkto /var/iog. 

Lockfilesare placed in this di rectory. The naming convention for device lock files is 

lck. .devi ce wheredev ce isthe device's name in the fi lesystem. The format used isthat 

ofHDU UUCP lock files- that is, lock files contain a PI D as a 10- byte ASC II decimai 

number, followed by a newlinecharacter. 

M iscellaneous log files. 

Thisiswherevi(l) saveseditsessionssotheycan be restored later. 
Runtimevariablefiles, such as files holding process identifiers (PID s) and logged user 
information (utmp). Files in this di rectory are usually cleared when the system boots. 
Spooled (orqueued) fi les for variousprograms. 
Spooled jobsforat(l). 
Spooled jobsforcron(l). 
Spooled fi les for printing. 
Users' mailboxes. 

Spooled files for the smaii(l) mail delivery program. 
Spool directory for the news subsystem. 
Spooled files for uucp(l). 

Like /tmp, this directory holdstemporary fi les stored for an unspecified duration. 



CONFO RMSTO 

TheLinuxfilesystem standard, releasel.2. 

BUGS 

This I i st isnot exhaustive; different systemsmay be confi gured differently. 
SEEALSO 

find(l), in(l), mount(l), proc(5), T he Linux F i I esystem Standard 



Linux, 10 February 1996 
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hostname— H ostname resolution descri ption. 



hostname 



DESCRIPTION 

H ostnames are domai ns. A domain isa hierarchical, dot-separated list of subdomains For example, themachinemonet in the 
Berkeley subdomain of theEDu subdomain of the Internet Domain N ame System is represented asmonet.Berkeiey.EDu (with 
notrailingdot). 

H ostnames are often used with network eli ent and server programs, which must general ly translate the nameto an address 
for use. (T his task isusually performed by the library routinegethostbyname(3).) The default method for resolving hostnames 
by the Internet name resolver isto follow RFC 1535'ssecurity recommendations. Actionscan betaken by theadministrator 
to overri de these recommendations and to have the resolver behave the sameasearlier, non-RFC 1535 resolvers. 

Thedefault method (using RFC 1535 guidelines) follows. 

If the name consistsof asinglecomponent (that is, containsno dot) and if theenvironment variableHosTALiASEs is set to the 
nameof a file, that file issearched for a stri ngmatching the input hostname. The file should consistof li nes madeup of two 
strings separateti by whitespace, the first of which is the hostname alias and thesecond of which is the complete hostname to 
besubstituted for that alias. If a case-insensitive match isfound between the hostname to beresolved and the first field of a 
li ne in the fi le, the substituted nameislooked up with no further processing. 

If thereisat least onedot in the name, then the name isfirst tried as is Thenumber of dotsto cause this action is 
confi gurableby setti ng the threshold using the ndots option in /etc/resoiv.cont (default isi). If the name ends with a dot, 
the trai li ng dot isremoved, and the remai ning nameislooked up (regardlessof the setti ng of the ndots option) and no 
further processing isdone. 

If the input name doesnot end with a trai li ng dot, it is looked up by searching through a list of domai ns unti I a match is 
found. If neither thesearch option in the /etc/resoiv.cont file or the localdomain environment vari ableis used, then the 
search list of domainscontainsonly thefull domain specified by thedomain option (in /etc/resoiv.cont) orthedomain 
used in the locai hostname (seenostname(l) and resoiver(5)). For example, if thedomain option is setto cs.Berkeiey.EDu, 
then onlycs.Berkeiey.EDu isin thesearch list and istheonly domain appended to the parti al hostname. For example, a 
settingof ìithium makesiithium.cs.Berkeiey.EDu theonly nameto betried using the search list. 

If thesearch option isused in /etc/resoiv.cont or the environment vari able, localdomain is set by theuser, then thesearch 
list includeswhat is set by these methods. For example, if thesearch option contai ned cs.Berkeiey.EDu cchem.Berkeiey.EDu 
Berkeiey.EDu, then the partial hostname(such as ìithium) istried with each domain nameappended (in thesameorder 
specified). The resulting hostnames that are tried include 

lithium.CS.Berkeley.EDU 

lithium.CChem.Berkeley.EDU 

lithium.Berkeley.EDU 

Theenvironment variable localdomain overri des the search and domain options, and if both search and domain optionsare 
presentin the resolver confi gu rati on file, then only the last one listed isused (see resoiver(5)). 

If the name wasnot previously tried "as is" (that is, it fell below the ndots threshold or did not contai n a dot), then the name 
asoriginally provided isattempted. 

SEEALSO 

gethostbyname(3), resolver(5), mailaddr(7), named(8) 

16 February 1994 

iso_8859_1 

iso_8859j — The ISO 8859-1 character set encoded in octal, decimai, and hexadecimal. 
DESCRIPTION 

ThelSO 8859 standard includes several 8-bit extensions to the ASC 1 1 character set (also known asISO 646-IRV). E speci al ly 
important islSO 8859-1, the Latin Alphabet N o. 1, which hasbecomewidely implemented and may al ready beseen asthe 
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de fatto standard ASCII replacement. ISO 8859-1 supportsthefollowing languages: Afrikaans, Basque, Catalan, Danish, 
Dutch, English, Faeroes, Finnish, French, Galician, German, Icelandic, Irish, Italian, Norwegian, Portuguese, Scottish, 
Spanish, and Swedish. N otethatthelSO 8859-1 charactersarealso the first 256 charactersof ISO 10646 (U ni code). 



ISO 8859 ALPH ABETS 

Thefull set of ISO 8859 alphabets includes 

ISO 8859-1 
ISO 8859-2 
ISO 8859-3 
ISO 8859-4 
ISO 8859-5 
ISO 8859-6 
ISO 8859-7 
ISO 8859-8 
ISO 8859-9 
ISO 8859-10 



WestEuropean languages (Latin-1) 

EastEuropean languages (Lati n-2) 

Southeast European and miscellaneous languages (Latin-3) 

Scandi navian/Baltic languages (Lati n-4) 

Latin/C yrillic 

Latin/Arabie 

Latin/G reek 

Latin/H ebrew 

Latin-1 modification for Turkish (Latin-5) 
Lappish/Nordic/Eskimo languages (Latin-6) 



ISO 8859-1 CHARACTERS 

T he following table displays the characters in ISO 8859 Latin-1, which are pri ntable and unlisted in theascii(7) manual 



page. 



Oct 



Dee 



Hex 



Char 



D escripti on 



240 
241 
242 
243 
244 
245 
246 
247 



160 
161 
162 
163 
164 
165 
166 
167 



A0 
Al 
A2 
A3 
A4 
A5 
A6 
A7 



N o-break space 

Inverted exclamation mark 

Cent si gn 

Pound sign 

Currency sign 

Yen sign 

Broken bar 

Serti on sign 



250 
251 
252 
253 

254 
255 
256 
257 
260 
261 
262 
263 



168 
169 
170 
171 

172 
173 
174 
175 
176 
177 
178 
179 



A8 
A9 
AA 
AB 

AC 
AD 
AE 
AF 
B0 
Bl 
B2 
B3 



© 



± 

2 
3 



D i aeresi s 

Copyri ghtsign 

Femi ni ne ordinai indicator 

Left-pointing doublé angle quotati on 
mark 

N ot sign 

Soft hyphen 

Registered sign 

M acron 

Degree sign 

Plus-minussign 

Superscri pttwo 

Superscri pt three 
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n a- 

U a. 


H m 


V. lidi 


n oc/ri nH nn 


264 


180 


B4 




Acute accent 


265 


181 


B5 




M icro sign 


266 


182 


B6 


1 


Pilcrow sign 


267 


183 


B7 




M iddledot 


270 


184 


B8 


? 


Cedilla 


271 


185 


B9 


1 


Superscri ptone 


272 


186 


BA 


o 


M ascul ine ordinai indicator 


273 


187 


BB 


» 


Right-pointing doubleangle 
quotati on mark 


274 


188 


BC 


1/4 


Vulgar fraction onequarter 


275 


189 


BD 


1/2 


Vulgar fraction onehalf 


276 


190 


BE 


3/4 


Vulgar fraction threequarters 


277 


191 


BF 


l 


Inverted question mark 


300 


192 


CO 


À 


Latin capital letter A with grave 


301 


193 


CI 


À 


Latin capital letter A with acute 


302 


194 


C2 


À 


Latin capital letter A with circumflex 


303 


195 


C3 


À 


Latin capital letter A with tilde 


304 


196 


C4 


À 


Latin capital letter A with diaeresis 


305 


197 


C5 


A 


Latin capital letter A with ringabove 


306 


198 


C6 


/E 


Latin capital ligatureAE 


307 


199 


C7 


c 


Latin capital lettere with cedilla 


310 


200 


C8 


È 


Latin capital letter E with grave 


311 


201 


C9 


É 


Latin capital letter E with acute 


312 


202 


CA 


É 


Latin capital letter E with circumflex 


313 


203 


CB 


È 


Latin capital letter E with diaeresis 


314 


204 


ce 


ì 


Latin capital letter 1 with grave 


315 


205 


CD 


1 


Latin capital letter 1 with acute 


316 


206 


CE 


ì 


Latin capital letter 1 with circumflex 


317 


207 


CF 


ì 


Latin capital letter 1 with diaeresis 


320 


208 


DO 


0 


Latin capital letter eth 


321 


209 


DI 


N 


Latin capital letter N with tilde 


322 


210 


D 2 


0 


Latin capital letter O with grave 


323 


211 


D3 


0 


Latin capital Ietterò with acute 


324 


212 


D4 


0 


Latin capital letter O with circumflex 


325 


213 


D5 


ò 


Latin capital letter O with tilde 


326 


214 


D6 


ó 


Latin capital Ietterò with diaeresis 


327 


215 


D7 


X 


M ultiplication sign 


330 


216 


D8 


0 


Latin capital Ietterò with stroke 


331 


217 


D9 


Ù 


Latin capital letter U with grave 


332 


218 


DA 


ù 


Latin capital letter U with acute 


333 


219 


DB 


G 


Latin capital letter U with circumflex 



continues 
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Oct 


Dee 


H ex 


C har 


D escripti on 


334 


220 


DC 


U 


Latin capital letter U with d i aeresi s 


335 


221 


DD 


Y 


Latin capital letter Y with acute 


336 


222 


DE 


n 


Latin capital letter thorn 


337 


223 


DF 


1? 


Latin small letter sharp s 


340 


224 


EO 


à 


Latin small letter a with grave 


341 


225 


El 


à 


Latin small letter a with acute 


342 


226 


E2 


à 


Latin small letter a with circumflex 


343 


227 


E3 


à 


Latin small letter a with tilde 


344 


228 


E4 


à 


Latin small letter a with diaeresis 


345 


229 


E5 


à 


Latin small letter a with ringabove 


346 


230 


E6 


ae 


Latin small ligatureae 


347 


231 


E7 


S 


Latin small lettere with cedi 1 1 a 


350 


232 


E8 


è 


Latin small letter ewith grave 


351 


233 


E9 


é 


Latin small letter ewith acute 


352 


234 


EA 


è 


Latin small letter ewith circumflex 


353 


235 


EB 


é 


Latin small letter ewith diaeresis 


354 


236 


EC 


ì 


Latin small letter i with grave 


355 


237 


ED 


i 


Latin small letter i with acute 


356 


238 


EE 


ì 


Latin small letter i with circumflex 


357 


239 


EF 


ì 


Latin small letter i with diaeresis 


360 


240 


FO 


a 


Latin small letter eth 


361 


241 


FI 


n 


Latin small letter n with tilde 


362 


242 


F2 


ò 


Latin small letter o with grave 


363 


243 


F3 


ó 


Latin small Ietterò with acute 


364 


244 


F4 


6 


Latin small letter o with circumflex 


365 


245 


F5 


5 


Latin small letter o with tilde 


366 


246 


F6 


ò 


Latin small Ietterò with diaeresis 


367 


247 


F7 




D ivision sign 


370 


248 


F8 


0 


Latin small letter o with stroke 


371 


249 


F9 


ù 


Latin small letter u with grave 


372 


250 


FA 


ù 


Latin small letter u with acute 


373 


251 


FB 


ù 


Latin small letter u with circumflex 


374 


252 


FC 


ù 


Latin small letter u with diaeresis 


375 


253 


FD 


y 


Latin small letter y with acute 


376 


254 


FE 


p 


Latin small letter thorn 


377 


255 


FF 


y 


Latin small letter y with diaeresis 



SEEALS0 

ascii(7) 



11 July 1995 
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locale 

Locale— D escri ption of multi-languagesupport. 
SYNOPSIS 

#include <locale.h> 

D ESC RI PTION 

A locale is a set oflanguage and cultural rules. Th eseco ver aspectssuch aslanguagefor messages, different character sets, 
lexigraphicconventions, and so on. A program needsto beableto determine its locale and act accordi nglyto beportableto 
different cultures. 

Theheader<iocaie.h> declares data types, functionsand macrosthatareuseful in thistask. 

Thefunctionsitdeclaresaresetiocaieo to set thecurrent locale and ìocaieconvo to get information about number 
formatting. 

There are different categoriesfor locai information a program might need; they aredeclared as macros. Using them asthe 
first argumentto thesetiocaieo function, it i s possi bleto set oneof theseto thedesired locale: 

lcjxjllate Thisisused to changethebehaviorof thefunctionsstrcoiio and strxfrmo, which 

areused to compare stri ngs in the locai alphabet. For example, theGerman sharp sis 
sorted as"ss." 

lc_type T hischanges the behaviorof the character handlingand classification functions, 

such asisuppero and touppero and the multi- byte character functions such as 

mblen() Orwctombf). 

lc_monetary C hanges the behavior of the i nformation returned by ìocaieconvo, which describes 

theway numbersareusually printed, with details such as decimai point versus 
decimai comma. 

lc_messages C hanges the language messages are displayed in. 

lc_time C hanges the behavior of thestrftimeo function to display thecurrent timein a 

locai ly acceptableform; for example, most of Europe uses a 24-hour clock versus the 
U.S. 12- hour clock. 

i_cjy_L Ali of theabove. 

If thesecond argumentto setiocaieo isempty stri ng for the default locale, it is determi ned using the followi ng steps: 

1. If there is a non-nuli environment variablei_c_ALL, thevalueof lc_all isused. 

2. If an environment variablewith the samenameas oneof the precedi ngcategoriesexists and is non-nuli, its value isused 
for that category. 

3. If there is a non-nuli environment variablei_ANG, thevalueof lang isused. 

Values about locai numericformattingaremadeavailablein astruct iconv returned by the ìocaieconvo function, which has 
thefollowing declaration: 

struct lconv 
{ 

/* Numeric ( non -monetary) information. */ 

char *decimal_point ; /* Decimai point character. */ 

char *thousands_sep; /* Thousands separator. */ 

/* Each element is the number of digits in each group; 

elements with higher indices are farther left. 

An element with value CHAR_MAX means that no further grouping is done. 

An element with value 0 means that the previous element is used for ali 

groups farther left. */ 

char *grouping; 

/* Monetary information. */ 
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/* First three chars are a currency symbol from ISO 4217. 
Fourth char is the separator. Fifth char is 1 1 . */ 
char *int_curr_symbol; 

char *currency_symbol; /* Locai currency symbol. */ 

char *mon_decimal_point; /* Decimai point character. */ 

char *mon_thousands_sep; /* Thousands separator. */ 

char *mon_grouping; /* Like 'grouping' element (above). */ 

char *positive_sign; /* Sign for positive values. */ 

char *negative_sign; /* Sign for negative values. */ 

char int_f rac_digits; /* Int'l fractional digits. */ 

char frac_digits; /* Locai fractional digits. */ 

/* 1 if currency_symbol precedes a positive value, 0 if succeeds. */ 

char_p_cs_precedes; 

/* 1 if a space separates currency_symbol from a positive value. */ 
char_p_sep_by_space; 

/* 1 if currency_symbol precedes a negative value, 0 if succeeds. */ 
char_n_csjrecedes; 

/* 1 if a space separates currency_symbol from a negative value. */ 
char_n_sep_by_space; 

/* Positive and negative sign positions: 

0 Parentheses surround the quantity and currency_symbol. 

1 The sign string precedes the quantity and currency_symbol. 

2 The sign string succeeds the quantity and currency_symbol. 

3 The sign string immediately precedes the currency_symbol . 

4 The sign string immediately succeeds the currency_symbol . */ 
char_p_sign_posn; 

char_n_sign_posn; 

}; 

C0NF0RMST0 

POSIX.l 

At the moment, the only locale supported by Linuxaretheportablec, posix (i denti cai totheC locale), iso-8859-1 
(European Latin-1), and koi-8 (Russi an) locales. 

SEEALSO 

setlocale(3), localeconf (3), locale(l), localedef(l) 

Linux, 24 Aprii 1993 



mailaddr 

maiiaddr— M ail addressi ng descri ption. 
DESCRIPTION 

M ail addressesarebased on the AR PAN ET protocol listed at the end of thismanual page. Theseaddressesarein the general 
format 

u s e r @d o ma i n 

A domai n is a hierarchical dotseparated list of subdomai ns. Forexample, theaddress 
ericgmonet . berkeley.edu 

isusually interpreted from rightto left. Themessageshould go to the ARPA nametables(which do not correspond exactly 
to the physi cai ARPAN ET) and then to the Berkeley gateway, after which it should go to the locai hostmonet. W hen the 
message reaches monet, it is del ivered to the user eric. 
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U nlikesomeother formsof addressing, thisdoesnot imply any routing. Thus, although this address is specified asan ARPA 
address, it might travel by an alternate routeif thatweremoreconvenient or efficient. For example, at Berkeley, the 
associated messagewould probablygo directlyto monet over the Ethernet ratherthan go via the Berkeley ARPAN ET 
gateway. 

ABBREVIATA N 

U nder certain circumstances, it might not benecessary to type the enti re domain name. In general, anything followi ng the 
first dot may beomitted if it isthesameas the domain from which you aresending themessage. For example, a user on 
caider.berkeiey.edu could send to ericftnonet withoutaddingtheberkeiey.edu becauseit isthesameon both sendingand 
recavi ng hosts 

Certain other abbreviationsmay bepermitted as special cases. For example, at Berkeley, ARPAN ET hosts may bereferenced 
withoutaddingtheberkeiey.edu aslongastheir namesdo not confi ictwith a locai host name. 

COMPATIBIUTY 

Certain old address formats are converted to thenew formatto provide compati bility with theprevious mail system. In 
parti cular, 

user@host .ARPA 

isallowed and 

host : u s e r 

is converted to 

u s e r @h o s t 

to beconsistentwith thercp(l) command. 
Also, thesyntax 

host luser 

is converted to 

user ghost .UUCP 

This is usually converted back to thehost iuser form beforebeing sent on for compati bility with older UU CP hosts. 

Thecurrent implementation isnot ableto routemessagesautomatically through theU UCP network. U nti I that ti me, you 
must explicitly teli the mail system which hosts to send your message through to getto your final desti nation. 

CASEDISTINCTIONS 

Domain names (anything after the gsign) may begiven in any mixtureof uppercaseand lowercasewith theexception of 
UUCP hostnames. M ost hosts accept any combi nation of case in usernames, with thenotableexception of multics sites. 

ROUTE-ADDRS 

Under some circumstances, it might be necessary to route a message through several hosts to get itto thefinal destination. 
Usually, this routing is done automatically, but sometimesit isdesirableto route the message manually. Addresses that show 
theserelays aretermed "route-addrs." These use thesyntax 

<@host a , ghost b :u s e r @host c> 

This specifies that the message should besent to host a, from there to host b, and finally to hostc. This path isforced even if 
there is a more efficient path to hostc. 

Route-addrs occur frequently on return addresses because these are generally augmented by the software ateach host. Itis 
generally possibleto ignoreall but the us e r @do ma i n partof the address to determinetheactual sender. 
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POSTMASTER 

Every site is requi red to haveauser or user alias designateci "postmaster" to which problemswith the mail system may be 
addressed. 

OTHER NETWORKS 

Someother networks can be reached by givi ng the nameof the network asthelast componentof the domai n.Thisis not a 
standard featureand might not besupported at ali sites. For example, messagesto CSN ET or BITN ET sitescan often be 

SenttO userehost . CSNET Or user Ghost .BITNET. 

BUGS 

The RFC 822 group syntax (gr oup inserì ,user 2 ,user3 ;) isnotsupported except in the special caseof group:; becauseof a 
conflict with old berknet-styleaddresses. 

Route-Address syntax isgrotty. 

UUCP- and ARPAN ET-styleaddressesdo not coexist politely. 
SEEALSO 

maii(l), sendmaii(8); C rocker, D . H ., Standard for the Format of Arpa Internet Text M essages, RFC 822. 

14 February 1989 



man 

man— M acrosto format man pages. 
SYNOPSIS 

groff -Tascii -man file ... 
groff -Tps -man file ... 
man [s ect i ori ] t i 1 1 e 

D ESC RIPTIO N 

Thismanual page explains the groff tmac.an macro package. This macro package should beused by developerswhen writing 
or porti ng man pages for Linux. It isfairly compatiblewith other versionsof this macro package, so porti ng man pages 
should not bea major problem (exceptions include the N ET-2 BSD release, which usesa total ly di fferent macro package). 

N otethat N ET-2 BSD man pages can beused with groff simply by specifying the -mdoc option instead of the -man option. 
Usingthe-mandoc option is, however, recommended becausethisautomatically detects which macro packageisin use 

PREAMBLE 

The first command in a man page should be 

.TH t i 1 1 e s ect i ori date s o u r ce ma nua I , 

ti 1 1 e Thetitle of the man page(such asMAN). 

secti on Thesection numbertheman page should beplaced in (such as7). 

date The date of thelast revision; remember to change this every ti me a changeis made 

to the man page becausethisisthemost general way of doingversion control, 
source Thesourceof the command. 

Forbì nari es, use something such asGN U, N ET-2, SLS D istribution, M CC 

D istribution. 

For system calls, usetheversion of the kernel that you arecurrently looking at: 
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Linux 0.99.11. 

For library cai Is, usethesourceof thefunction: GNU, BSD 4.3, LinuxDLL 4.4.1. 
manuai T he title of the manual (such asLinux Programmer'sM anual). 

Themanual sectionsare traditionally defined asfollows: 

1 Commands Thosecommandsthat can beexecuted by the user from within ashell. 

2 System calls Thosefunctionsthat must beperformed by the kernel. 

3 L ibrary calls Mostof the ìibcfunctions, such assort(3). 

4 Special files Files found in /dev. 

5 Fileformatsand conventions Theformatfor /etc/passwd and other human-readablefiles. 

6 Games 

7 M acro packagesand conventions A descri ption of thestandard file system layout, thisman page, and other things. 

8 System management commands Commands such asmount(8), which only root can execute. 

9 Kernel routines Thisisanon-standard manual section and isincluded because the source code to 

the Linux kernel isfreely available under the GNU Public Licenseand many 
people are working on changes to the kernel. 
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Although there are many arbitrary conventions for man pages in theU N IX world, theexistenceof several hundred Linux- 
specificman pages defines the standards: 

Forfunctions, thearguments arealways specified using italiesi even in thesYNOPsis section, wheretherest of thefunction is 
specified in bold: 

int myf unction(int erge, char **argv); 

Filenames arealways in itali cs (such as /usr/inciude/stdio.h), except in thesYNOPsis section, whereincluded files are in bold 

(SUCh as#include <stdio.h>). 

Special macros, which are usually in uppercase, are in bold (such as maxint). 

When enumerati ng a list of errar codes, thecodesarein bold (this list usually usesthe .tp macro). 

Any referenceto anotherman page(ortothesubjectofthecurrentman page) isin bold. Ifthe manual section numberis 
given, itisgiven in roman, without any spaces (such asman(7)). 

The commands to select the typeface are given below: 

.b Bold 

.bi Bold alternati ngwith italics 

.br Bold alternati ngwith Roman 

.i Italics 

.ib Italics alternati ngwith bold 

.ir Italics alternati ngwith Roman 

.rb Roman alternati ngwith bold 

.ri Roman alternati ngwith italics 

.sb Small alternati ngwith bold 

.su Small 

Traditionally, each command can haveup to sixarguments, but theGN U version seemsto remove this li mitation. 
Argumentsaredelimited by spaces. Doublequotescan beused to specify an argumentthat contai ns spaces. Ali the 
argumentswill beprinted next to each other without intervening spaces, so that the .br command can beused to specify a 
word in bold followed by a mark of punctuation in Roman. 
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SECTIONS 

Sectionsarestarted with .sh followed by the heading name. If the name contai nsspaces and appearson thesamelineas .sh, 
then place the heading in doublé quotes. Traditional headings include name, synopsis, description, options, files, see also, 
diagnostics, bugs, and author. Theonly required heading ìsname, which should be followed on thenext lineby aoneline 
description of the program: 

.SH NAME 

chess \- the game of chess 

It isextremely important that this format is followed and that thereisa backslash beforethe single dash that follows the 
command name. This syntax isused by themakewhatis(8) program to create a database of short command descriptionsfor 
thewhatis(l) and apropos(l) commands. 

OTHER MACROS 

Other macrosincludethefollowing: 

.dt D efault tabs. 

.hp Begin hanging indent. 

.ip Begin paragraph with hanging tag. This isthesameas .tp, except thetag isgiven on the 

sameline, not on thefollowing line. 
.lp Sameas.pp. 
.pd Set interparagraph distanceto argument. 

.pp Begin a new paragraph. 

.re End relative indent (indented paragraph). 

.rs Start relative i ndent (indented paragraph). 

.ss Subheading (like .sh but used for a subsection). 

.tp Begin paragraph with hanging tag. Thetag isgiven on thenext line. This command is 

similarto .ip. 

FILES 

/ usr/ locai/ lib/grof f/tmac/tmac . an 
/usr/man/whatis 

SEE ALSO 

groff(l), man(l), whatis(l), apropos(l), makewhatis(8) 

Linux, 25 July 1993 



signal 

signai— List of avai lable si gnals. 
DESCRIPTION 

Linux supports the signals listed in this section. Several signal numbersarearchitecturedependent. First are the signals 
described in POSIX.l: 

abort(3) aiarm(l) N ext vari ous other sign al s. 

(H ere, - denotes that a signal isabsent; there, wherethreevaluesaregiven, the first one is usually valid for alpha and sparc, 
the middle one for i 386 and ppc, thelast onefor mips. Signal 29 ìssiginfo/sigpwr on an alpha but siglost on a sparc.) 



T he lettere in the Action column havethefollowing meanings: 



A Default action isto terminatetheprocess. 

B Default action isto ignorethesignal. 

C Default action isto dump core. 

D D efault action isto stop the process. 

E Signal cannot becaught. 

F Signal cannot beignored. 

G Not a PO SIX.l conformarti signal. 



CONFORMINO TO 

POSIX.l 

BUGS 

sigio and siglost havethesamevalue. Thelatter iscommented out in the kernel source, but the bui Id process of some 
software stili thinksthat Signal 29 ìssiglost. 

SEEALSO 

kill(l), kill(2), setitimer(2) 

Linux 1.3.88, 14 Aprii 1996 

suffixes 

suff ixes— List of file suffixes. 
DESCRIPTION 

It iscustomary to indicatethecontentsof afilewith thefilesuffix, which consistsof a period followed by oneor more 
lettere. M any standard Utilities, such as compi lers, usethisto recognize the typeof file they are deal ingwith. Themake(l) 
utility isdriven by rules based on fi le suffixes. 

Following isa list of suffixes that are li kely to befound on a Linux system: 



Suffix 


FileType 


,v 


Filesfor RCS (Revision Control System) 




Backup file 


.C 


C++ source code 


.F 


FORTRAN source with cpp(l) di rectives 


.S 


Assembler source with cpp(l) directives 


2 


Filecompressed using compress(l) 


.[0-9]4pk 


TeX fontfiles 


.[1-9] 


M anual page for the corresponding section 


.[l-9][a-z] 


M anual page for section plussubsection 


.a 


Static object code library 


.afm 


PostScript font metri cs 


.are 


ARC archive 


.arj 


ARJ archive 


.asc 


PGP ASCII-armored data 



continue 



Suffix FileType 

.awk AWK language program 

.bak Backup file 

.bm Bitmapsource 

.c C source 

.cat M essage catalog files 

.ce C++ source 

.cf Configuration file 

xonf Configuration file 

.config Configuration file 

.cweb Donald Knuth'sWEB forC 

.dat Data fi le 

.def M odula-2 sourcefor definition modules 

.def Other definition files 

.diff ASCII Filedifferences 

.doc Documentation file 

.dvi TeX device independent output 

.el EMACSIisp source 

.eie Compiled EMACSIisp 

.eps E ncapsulated PostScript 

.f FORTRAN source 

.fas Precompiled common lisp 

.fi FORTRAN includefiles 

.gif Graphics Interchange Format 

.gsf Ghostscriptfonts 

.gz Filecompressed usinggzip(l) 

.h C orC++headerfiles 

.hip Help file 

.htm HTML file imported without renami ngfrom a brai n-damaged OS 

.html HTML document used with the World W ideWeb 

.i C source after preprocessing 

.idx Reference or datum-index fi le for hypertext or database system 

.icon Bitmapsource 

.image Bitmapsource 

.in Configuration template, especially for GNU autoconf 

.info Files for the EM AC S info browser 

.java A Java source fi le 

.jpg JPEG compressed pictureformat 

.1 iex(l) or fiex(l) files 

Jib Common lisp library 

.In Filesfor usewith iint(l) 

.Isp Common lisp source 

.m4 M4(l) source 

.mac M acro filesfor vari ous program s 



suffixs 



Suffix 


FileType 


.man 


M anual page (usually source rather than formatted) 


.me 


nrof f source usi ng the me macro package 


.mf 


M etafont (font generator for T eX ) source 


.mm 


Sourcesforgroff(l) in mm format 


.mod 


M odula-2 source for implementation modules 


.0 


0 bject file 


.old 


Old or backup file 


.orig 


Backup (originai) version of afilefrom patch(l) 


.out 


Output file, often an executable program (a. out) 


■P 


Pascal source 


.patch 


Filedifferences from patch(l) 


.pcf 


Xllfontfiles 


.pfa 


PostScript font definition files, ASCII format 


.pfb 


PostScript font definition files, binary format 


■pgp 


PGP binary data 


. pi d 


Fileto storedaemon PID (such ascrond.pid) 


■png 


Portable N etwork Graphics file 


.pi 


Perl script 


■pr 


Bitmap source 


■ps 


PostScript fi le 


.r 


RAT FOR source (obsolete) 


■rej 


Patchesthat patch(l) couldn't apply 


.rules 


Rulesforsomething 


.s 


Assembler source 


.sa 


Stub librariesfora.out shared libraries 


.se 


sc(l) spreadsheet commands 


.sh 


sh(l) scripts 


.shar 


Archivecreated by theshar(l) utility 


.so 


D LL dynamic library 


.sqml 


SQ M L schema or query program 


■sty 


LaTeXstyle files 


.sym 


M odula-2 compiled definition modules 


.tar 


Archivecreated bythetar(l) utility 


.tar.Z 


tar archi ve compressed with compress(l) 


.tar.gz 


tar archivecompressed with gzip(l) 


.taz 


tar archivecompressed with compress(l) 


.tex 


TeX or LaTeX source 


.texi 


Equivalentto .texinfo 


.texinfo 


TeXinfo documentation source 


.tfm 


TeX fontmetrics 


.tgz 


tar archivecompressed with gzip(l) 


.tmpl 


T empiate files 



continue 
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Qi iffi v 
J\i\\\ X 


F i 1 e T ype 


.txt 


Text file 


.uue 


Binary file encoded with uuencode(l) 


.web 


Donald Knuth'sWEB 


■y 


yacc(l) or bison(l) (parser generatori files 


.z 


Filecompressed using pack(l) (or an old gzip(l)) 


.zoo 


ZOO archi ve 




E MAC Sor patch backup fi le 


re 


Startup (run control) file, SUCh as .newsrc 



C0NF0RMST0 

General UN IX conventi ons. 

BUGS 

Thislist isnot exhaustive 
SEEALSO 

file(l), make(l) 

Linux, 4 Aprii 1996 



tr2tex 

tr2tex— C onvert a document from troff to LaTex 
SYNOPSIS 

tr2tex [ -ni ] f i I e n a me 

D ESC RIFTIO N 

tr2tex converts a document typeset in troff to a LaTeX format. Itisi ntended to do the first passof the conversi on. The user 
should then finish up therest of theconversion and customizetheconverted manuscript to hisor her liking. It can also serve 
asatutorforthosewho wantto convertfrom troff to LaTeX. 

M ostof theconverted document wi II be in LaTeX, but someof it may bein piai n TeX. It wi II also usesomemacrosin 
troffms.sty or troff man . sty, which areincluded in the package and must beavailableto the document when processed with 
LaTeX. 

If thereismorethan oneinputfile, they wi II ali beconverted into oneLaTeX document. 

tr2tex understands most of the -ras and man macrosand eqn preprocessor symbols. It also understandsseveral piai n troff 
commands. Few tbi preprocessor commandsareunderstood to help convert very simpletables. 

When converting manuals, use the -m flag. 

If a troff command cannot beconverted, the li ne that contai n that command will becommented out. 

Notethat if you haveeqn symbols, you must have the inline mathematics delimiter defined bydeiim in thefileyou are 
converting. If it is defined in another setup file, that setup file must beconcatenated with the fi le to beconverted; otherwise, 
tr2tex regards theinlinemath as ordì nary text. 



U nicode 



BUGS 

M any of thesebugsareharmless. Mostof them cause locai errorsthat can befixed in theconverted manuscript. 

■ Some macros and macro arguments are not recognized. 

■ Commandsthat are not separated from their argument by a space are not properly parsed (such as .sp3i). 

■ When some operators (notably over, sub, and sup) arerenamed (via define) and then they are encountered in thetext, 
tr2tex treats them as ordì nary macros and does not apply thè r rules. 

■ rpiie, ìpiie, and cpiie are treated the same as cpiie. 

■ rcoi and icoi are treated the same asccoi. 

■ M ath-modesize, gsize, fat, and gfont areignored. 

■ ìineup and mark are ignored. T he rules are so different. 

■ Sometroff commandsaretranslated to commandsthat requiredelimitersthat haveto beexplicitly put. Becausethey 
aresometimes not put in troff, they can create problems. Example: .nf isnot closed by .fi. 

■ When locai motionsareconverted to nraise orniower, an nhbox isneeded, which must be put manually after the 
conversi on. 

■ a sub i sub j isconverted to a_i_j, which TeX parsesasa_i{}j> with acomplaint that it isvague. a sub {i sub]} is 
parsed correctly and converted to a_{ij>. 

■ Linespacing isnot changed within a paragraph in TeX (which isa bad practiceanyway). TeX usesthelast linespacing 
in effect in that paragraph. 

TODO 

Access regi sters vi a the . nr command. 
SEEALSO 

texmatch(9), trmatch(9) 

AUTHOR 

Kamal Al-Yahya, Stanford U niversity 

1 January 1987 



Unicode 

U nicode— Theunified 16-bit super character set. 
DESCRIVO N 

Theinternational standard ISO 10646 defines the U ni versai Character Set (UCS). UCS contai nsall the characters of ali 
other character-set standards. It also guarantees round-trip compati bility; conversion tablescan bebuilt such that no 
information islost when a stri ng isconverted from any other encoding to UCS and back. 

UCS contai ns the characters required to represent almost ali known languages. T his includes apart from themany languages 
that use extensionsof theLatin script also the followi ng scripts and languages: Greek, Cyrillic, H ebrew, Arabie, Armenian, 
Gregorianjapanese, Chinese, H iragana, Katakana, Korean, H angui, Devangari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, 
Telugu, Kannada, M alayam.Thai, Lao, Bopomofo, and a number of others. Work isgoingon to include further scripts such 
asTibetan, Khmer, Runic, Ethiopian, H ieroglyphics, variousIndo-European languages, and many others. For most of these 
latter scripts, it wasnot yet clear how they can beencoded best when thestandard waspublished in 1993. In addition to the 
characters required by these scripts, also al arge number of graphical, typographical, mathematica!, and sci entifi c symbols 
such asthose provi ded byTeX, PostScript, M S-DOS, M acintosh, Videotext, OCR, and many word processing system sh ave 
been included, aswell as speci al codesthatguaranteeround-tripcompatibilityto ali other existing character-set standards 
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TheUCS standard (ISO 10646) descri bes a 31-bit character-set architecture; however, todayonly the first 65534 code 
positions (0x0000 to Oxfffd), which arecalled the Basic M ultilingual Piane (BM P), havebeen assigned characters, and it is 
expected that only very exotic characters (such asH ieroglyphics) for special scienti fic purposeswill ever get a place outsi de 
thisl6-bitBM P. 

TheUCS characters 0x0000 to 0x007f are i denti cai to thoseof the classic US-ASC II character set and the characters in the 
rangeOxOOOO to OxOOff are i denti cai to thosein the ISO 8859-1 Latin-1 character set. 

COMBINING CHARACTERS 

Some code points in UCS have been assigned to combi ni ng characters. These are similar to the non-spaci ng accent keyson a 
typewriter. A combini ng character just addsan accent to the previ ous character. Themost important accented characters 
havecodesof their own in UCS; however, the combini ng character mechanism allowsyou to add accentsand other 
diacritical marksto any character. The combini ng characters alwaysfollow the character that they modify. For example, the 
German character U mlaut- A ("Latin capital letter A with diaeresis") can either be represented by the precorri posed UCS code 
0x00c4 or alternatelyas the combi nation of anormal "Latin capital letter A" followed by a "combi ni ng diaeresis": 0x0041 
0x0308. 

IMPLEM EN TATION LEVELS 

As notali systems are expected to support advanced mechanismssuch ascombining characters, ISO 10646 specifiesthe 
following three implementation levels of UCS: 

Level 1 Combining characters and H angui J amo characters (a special, morecomplicated encoding 

of theKorean script, whereH angui syllablesarecoded astwo or three subcharacters) arenot 
support ed. 

Level 2 Like level 1, except in some seri pts, some combi ni ng characters are now allowed (such as 

H ebrew, Arabie, Devangari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugo, Kannada, 
M alayalam, Thai, and Lao). 

Level 3 Ali U C S characters are supported. 

T he U ni code 1.1 standard pubi ished by the U nicode Consorti um containsexactly theUCS Basic M ultilingual Piane at 
implementation Level 3, as descri bed in ISO 10646. U nicode 1.1 al so adds some semanti cai definiti ons for some characters 
to thedefinitionsof ISO 10646. 

UNICODEUNDER LINUX 

U nder Linux, only the BM P at implementation Level 1 should beused at the moment to keep the implementation 
complexity of combining characters low. Thehigher implementation levels are more suitable for special word processing 
formatsbut not as a generi c system character set. The C typewchar_t ison Linux an unsigned 16- bit integer typeand its 
valuesareinterpreted asU CS Level 1 BM P codes. 

The locale setti ng specifieswhether the system character encoding isUTF-8 or ISO 8859-1, for example. Libraryfunctions 
such aswctomb, mbtowc, or wprintf can beused to transform the internai wchar_t characters and strings into the system 
character encoding and back. 

PRIVATE AREA 

In the BM P, therangeOxeOOO to 0xf8ff will never be assigned any characters by the standard and isreserved for private 
usage. For the Linux community, this private area issubdivided further into therangeOxeOOO to Oxefff, which can beused 
individuai ly by any end user and the Linux zone in therangeOxfOOO to 0xf8ff whereextensions are coordinate^ amongall 
Linux users. The regi stry of the characters assigned to the Linux zone iscurrently maintained by H . Peter Anvin 
(peter.AnvinWinux.org), Yggdrasil Computing, Inc. It contai ns some D EC VT100 graphics characters missing in U nicode, 
gives direct access to the characters in the console font buffer, and contai ns the characters used by a few advanced seri pts such 
asKIingon. 



LITERATU RE 

Information technology— U ni versai M ultiple-0 ctet Coded Character Set (U CS). Part 1: Architetture and Basic M ulti linguai 

Piane. International Standard ISO 10646-1, International Organization forStandardization, Geneva, 1993. 

Thisisthe officiai specifi cation of UCS. Pretty officiai, prettythick, and pretty expensive. Forordering informati on, check 

www.iso.ch. 

TheU ni code Standard— WorldwideCharacter Encoding Version 1.0. TheUnicodeConsortium, Addison-Wesley, Reading, 
MA, 1991. 

There is al ready U nicode 1.1.4 available Thechangesto the 1.0 book areavailablefrom ftp.unicode.org. U nicode 2.0 wi II 
be pubi i shed again as a book in 1996. 

S. H arbison, G. Steele. C, A ReferenceM anual. Fourth edition, PrenticeH ali, Englewood Cliffs, 1995, 
ISBN 0-13-326224-3. 

A good referencebook abouttheC program mi ng language. The fourth edition now coversalso the 1994 Amendment 1 to 
thelSO C standard (ISO /I E C 9899:1990), which adds a large number of new C library functionsfor handling wide 
character sets. 

BUGS 

At thetimewhen thisman pagewaswritten, the Linux libo support for UCS wasfarfrom complete. 
AUTHOR 

M arkus Kuhn (mskuhn@cip.informatik.uni-erlangen.de) 

SEEALSO 

utf -8(7) 

Linux, 27 December 1995 

UTF -8 

utf -8— An ASC II -compati ble multi byte U nicode encoding. 
DESCRIPTION 

TheU ni code character set occupi es a 16-bit codespace. The most obviousU nicode encoding (known asUCS-2) consists of 
asequenceof 16-bit words. Such stringscan contai n as parts of many 16-bit charactersbytessuch as\o or /, which havea 
special meaning in filenamesand other C library function parameters. In addition, the majority of U N IX toolsexpects 
ASCII filesand can't read 16-bit words ascharacterswithout major modificati ons. For these reasons, UCS-2 isnot a suitable 
external encoding of U nicode in filenames, text files, environment variables, and so on. ThelSO 10646 U niversal Character 
Set (UCS), asuperset of U nicode, occupieseven a 31-bit codespace, and theobviousUCS-4 encoding for it (asequenceof 
32- bit words) hasthesameproblems. 

TheUTF-8 encoding of U nicode and U CS doesnot havetheseproblemsand istheway to go for usi ng the U nicode 
character set under U N IX-style operati ng systems. 

PROPERTIES 

TheUTF-8 encoding has thefollowing niceproperties: 

UCS characters 0x00000000 to 0x0000007f (the ci assi cai U .5. ASC 1 1 characters) are encoded simply as bytes 0x00 to 0x7f 
(ASCII compati bi li ty). Thismeansthat files and stringsthat contai n only 7-bit ASC 1 1 characters have the same encoding 
under both ASCII and UT F-8. 

Ali U C S characters greater than 0x7f are encoded as a multi byte sequence consisti ng only of bytes in the range 0x80 to Oxfd, 
so no ASC II bytecan appear as part of another character and there are no problemswith \eor /. 
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The lexi cographic sorti ngorder of U CS-4 stringsis preservai. 
Ali possi ble 2"31 UCS codescan beencoded using UTF-8. 
Thebytes Oxfeand Oxff arenever used in the UTF-8 encoding. 

The first byteof a multi byte sequencethat represents a single non-ASC II UCS character isalways in therangeOxcO to Oxfd 
and indicates how long this multi byte sequenceis. Ali further bytes in a multi byte sequence are in the range 0x80 to Oxbf. 
Thisallows easy resynchronization and makestheencodingstatelessand robust against missing bytes. 
UTF-8-encoded U CS characters may beup to six bytes long; however, U nicodecharacters can only beup to th ree bytes 
long. Because Linux uses only the 16-bit U nicode subset of UCS, under Linux, UTF-8 multi byte sequences can only beone, 
two, or three bytes long. 

ENCODING 

Thefollowing byte sequences are used to represent a character. The sequence to beused dependson theUCS codenumber 
of the character: 

0x00000000 - 0X0000007F: 0x x x x x x x 
0x00000080 - 0X000007FF: 110xxxxx 10xxxxxx 
0x00000800 - 0X0000FFFF: 1110xxxx 10xxxxxx 10xxxxxx 
0x00010000 - 0x001 FFFFF: 11110XXX 10xxxxxx 10xxxxxx 10xxxxxx 
0x00200000 - 0X03FFFFFF : 111110XX 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 
0x04000000 - 0X7FFFFFFF: 1111110X 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 
1 0x x x x x x 

Thexxx-bit positi ons are fi lied with the bits of the character codenumber in binary representation. 0 nly the shortest 
possi ble multi byte sequence that can represent the code number of the character can be used. 

EXAMPLES 

T he U ni code character 0xa9 =1010 1001 (the copyright sign) isencoded in UTF-8 as 

11000010 10101001 = 0xc2 0xa9 

and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is encoded as 

11100010 10001001 10100000 = 0xe2 0x89 0xa0 

STANDARD S 

ISO 10646, U nicode 1.1, XPG4, Pian 9. 

AUTH0R 

M arkus Kuhn (mskuhn@cip.informatik.uni-erlangen.de) 

SEEALSO 

unicode(7) 
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intro 

intro— Introduction to administration and privi leged commands. 
D ESC RIPTIO N 

T his chapter descri bes commandsthateithercan beor areonly used by thesuperuser, such asdaemonsand machineor 
hardware- rei ated commands. 

AUTHORS 

Look at the headerof the manual page for the authors and copyright conditions. Notethatthesecan bedifferentfrom page 
to page. 

Linux, 24 J uly 1993 



adduser, addgroup 

adduser, addgroup— Add a user or group to the system. 
SYNOPSIS 

adduser [--system [--home directory] [--group]] [--quiet] 
[--force- badname ] [ - - h e I p ] [--versi ori] [--debug] username 
adduser [--quiet] [ - -f or c e- ba d n a me ] [ — h e I p ] [--version] 
[ - -debug ] user name group 

adduser [--group] [--quiet] [ - -f or c e- bad n a me ] [ — h e I p ] 
[--version] [ - -debug ] group 

D ESC RIPTIO N 

adduser and addgroup add usersand groupsto the system accordi ng to information provided in theconfiguration file/etc/ 
adduser. conf. adduser and addgroup automatically determi ne the U I D orGID and place the entity in the password or 
group file as appropriate. 

If necessary, adduser creates a home directory for the new user, copies "skeletal" userfilesto it from /etc/skei, and allows 
thesystem admi nistratorto set an initial password and finger information fortheuser. 

Becauseit needsto beableto writeto such filesas /etc/passwd, adduser can only berun asroot. 

Generally, therearetwo typesof usersand groupson a system: thoseusersthat log into thesystem and those "non-user" 
accountsand groupsthat exist for various system tasksand projects. H enceforth, user wi II referto thelogin typeand system 
user or group will referto thetypeused for system maintenanceand projects. 

By default, each user in Debian GN U /Linux isgiven a corresponding group with the same name and ID, allowing people 
easilyto gi ve access to theirhomedirectoriesto others. T his opti on can beturned off in theconfiguration file, in which case 
each user is, by default, added to a group called users. 

U nder Debian GN U /Linux, IDslessthan or equal to 100 are allocated by the base system maintainer for various purposes. 
IDsfrom 101 to thevaluespecified in theconfiguration fi le (1000, by default) are used for system usersand groups. IDs 
greater than 1000 arereserved for usersand their corresponding groups. 

When invoked with a single name, adduser creates a user with that name. W hen given two names, adduser assumesthat the 
first name represents an existinguser and that the second namerepresentsan existing group. In thiscase, the user is added to 
the group. 



agetty 
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OPTIONS 

- -system 



- home di r ect or y 



-group 



-quiet 

-force-badname 



-help 
- version 
-debug 



C reate a system user. Thisuserwill beassigned theshell /bin/taise and havean 
asterisk in the password field. U nlessotherwisespecified, the user wi II beplaced 
in thegroup nogroup. Skdetal configuration fileswill not becopied into the 
user's home directory. 

When used with - -system, thisusesdi rectory as the user's home directory, 
rather than the default specified in the configuration file. If the directory does 
notexist, it iscreated. 

When combined with -system, a group with thesamenameand ID asthe 
system user iscreated. If not combined with --system, a group with thegiven 
name iscreated. Thisis the default action if the program is invoked asaddgroup. 
Suppress progress messages. 

By default, user and group names are required to consist of a lowercase letter 

followed by one or more lowercase letters or numbers. Thisoption forces 

adduser or addgroup to be more lenient. 

D isplay brief instructions. 

D isplay version and copyright information. 

D isplay a large quantity of debugging information. 



SEEALSO 

adduser. conf(5) 

COPYRIGHT 

Copyright(c) 1995, Ted H ajek, with agreatdeal borrowed from theoriginal Debian adduser, copyright(c) 1994, lan 

M urdock. adduser isf ree software; seetheGN U General Public Licen se version two or laterfor copyingconditions. Thereis 

no warranty. 

Debian GNU /Linux version 1.94 



agetty 

agetty— Alternative Linux getty. 

SYNOPSIS 

agetty [ -ihL] [-1 logìnprogram] [ - ni] [-t timeout] port ba ud_ r at e , . . . [ t e r m ] 
agetty [ - ihL] [-1 logìnprogram] [ - ni] [-ttimeout] baud_rate,... port [t er m] 

DESCRIPTION 

agetty opens a tty port, promptsfor a login name, and invokesthe /bin/iogin command. It isusually invoked by imt(8). 

agetty hasseveral non-standard featuresthat areuseful for hard-wired and for dial-in lines: 

Adaptsthetty setti ngs to parity bitsand to erase, kill, end-of-line, and uppercasecharacterswhen it readsa login name. 
The program can handle 7-bit characterswith even, odd, none, or space parity and 8-bitcharacterswith no parity. The 
following special charactersarerecognized: @ and Control -HJ (kill); #, Del and Backspace (erase); carri age return and line 
feed (end of line). 

0 ptionally deducesthe baud rate from thecoNNECT messages produced by H ayes-compatiblemodems. 
Optionally does not hangup when it isgiven an already opened li ne (useful for cali-back applications). 
0 ptionally does not display the contents of the /etc/issue file (System V only). 
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0 ptionally invokes a non-standard login program instead of /bin/iogin. 

Optionallyturnson hardware flow control. 

0 ptionally forces the line to be locai with no need for carrier detect. 

This program does not use the /etc/gettydefs (System V) or /etc/gettytab (SunOS 4) files. 



ARGUMENTS 

port 



baud rate, 



terni 

0PTI0NS 

-h 



-1 I ogi n_program 



- 1 t i me o y t 



-L 



A path name relative to the/dev directory. If a - isspecified, agetty 
assumesthat its standard input is al ready connected to atty port and that 
a connection to a remote user has al ready been established. U nder System 
V, a - port argument should be preceded by a -. 
A comma-separated list of oneor more baud rates. Each ti me agetty 
receives a break character, it advancesthrough the list, which istreated as 
if it were circular. Baud rates should bespecified in descendi ngorder, so 
thatthenull character (C tri-Kg)) can also beused for baud rate switching. 
Thevalueto beused for the terni environment vari able. This overrides 
whatever mit(8) may haveset and isinherited by login and theshell. 



E nable hardware (RTS/CTS) flow control. Itisi ef t u p to the application 
to di sabl e software (XON/XOFF) flow protocol wh ere appropriate. 
Do not display the contentsof /etc/issue before writing the login 
prompt. Terminals or Communications hardware might become confused 
when receiving lotsof textat the wrong baud rate; dial-up scripts might 
fail if thelogin prompt is preceded by too much text. 
I nvoke the specifi ed login program instead of /bin/iogin. Thisallows 
the use of a non-standard login program (forexample, onethatasksfora 
dial-up password or that usesadifferent password file). 
Try toextract the baud rate the connect status message produced by some 
H ayes- co m pati bl e m odem s. T h ese status m essages are of th e fo rm : 
"<junk><speed><j unk>" . agetty assumes that the modem em its its 
status message at the sam e speed asspecified with (the first) baud rate 
valueon thecommand line. 

Becausethe -mfeature might fail on heavily loaded systems, you stili 
should enable break processing by enumerating ali expected baud rates on 
thecommand line 

T ermi nate if no usemamecould beread within t i meo ut seconds. This 
option should probably not beused with hard-wired lines. 
Force the li ne to bea locai li ne with no need for carrier detect. This can 
beuseful when you havea locai ly attached terminal wheretheserial line 
does not set the carrier detect signal. 



EXAMPLES 

Thissection shows sample entri es for the /etc/imttabfile. 
For a hard-wired line: 

ttyl :con80x60: /sbin/agetty 9600 ttyl 

Foradial-in linewith a 9600/2400/1200 baud modem: 

ttyS1:dumb: /sbin/agetty -mt60 ttyS1 9600,2400,1200 



agetty 
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Theseexamples assume you usethesimpieinit(8) imt program for Linux. If you use a SysV-likemit (does /etc/inittab 
mention "respawn"?), referto the appropriate manual page. 

ISSU E ESCAPES 

The/etc/issue file might contai n certain escape codesto display the system name, date and ti me and so on. Ali escape 
codesconsistof a backslash (\) immediately followed by oneof thefollowing letters: 

b I nsert the baudrate of thecurrent line, 

d I nsert thecurrent date 

s I nsert the system name, the name of the operati ng system. 

1 I nsert the name of thecurrent tty line. 

m I nsert the architecture identifier of the machine, such asi486. 

n I nsert the nodenameof the machine, also known asthehostname. 

o I nsert the domain name of the machine 

r Insertthereleasenumberof the OS, such as 1.1.9. 

t I nsert the currenttime. 

u I nsert the numberof currentuserslogged in. 

u I nsert the stri ng 1 userorn userswheren isthe numberof currentuserslogged in. 

v I n sert the versi on of theOS, such asthebuild date and so on. 

For example, on my system, thefollowing /etc/issue file 

This is \n. \o (\s\m\r) \t 

displaysas 

This is thingol.orcan.dk (Linux Ì386 1.1.9) 18:29:30 

FILES 

/var/run/utmp, the system status file 
/etc/issue, printed beforethelogin prompt (System V only) 
/dev/consoie, problem reports (if sysiog(3) isnotused) 
/etc/inittab (Linux simpieinit(8) confi gurati on file) 

BUGS 

The baud-rate detection feature(the -m option) requiresthat agetty bescheduled soon enough after completion of adial-in 
cali (within 30mswith modemsthat talk at 2400 baud). For robustness, alwaysusethe -m option in combination with a 
multiple baud rate command-lineargument so that break processing isenabled. 

Thetext in the/etc/issue file and thelogin prompt arealways output with 7-bit charactersand space parity. 

The baud-rate detection feature(the -m option) requiresthat the modem emitsits status message after raisingtheDCD line. 

DIAGNOSTICS 

D ependi ng on how the program was confi gured, ali diagnostics are written to the console device or reported via the 
sysiog(3) facility. Errar messages are produced if theportargument does notspecify a terminal device, if thereis no utmp 
entry for the current process (System V only), and so on. 

AUTHORS 

W.Z. Venema (wietse@wzv.win.tue.ni) Eindhoven U niversity of Technology, D epartment of M athematicsand Computer 
Science, Den Dolech 2, P.O. Box 513, 5600 M B Eindhoven, The N etherlands. 

Peter Orbaek (poe@daimi.aau.dk), Linux port. 
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CREATION DATE 

Sat Nov 25 22:51:05 M ET 1989 

LAST MODIFICATION 

91/09/01 23:22:00 

VERSIO N/RELEASE 

1.29 



archive 

archive— U senet article archi ver. 
SYNOPSIS 

archive [ -a archive ][-f][-i index ][-m ][-r ][input ] 

DESCRIVO N 

archive makes copies of fi les specified on its standard input. It isusually run either asachannel feed under innd(8) or by a 
script before expire(8) isrun. 

archive reads the named input fi le or standard input if no fi le is given. The input istaken asaset of lines. Blank linesand 
li nes starti ng with a number sign (#) areignored. Ali other lines should specify thenameof afileto archive. If a fi lename is 
notan absolute pattinarne, it istaken to be relative to /news/spooi. 

Filesarecopied to adirectory within the archive directory, /news/spooi/news. archive. The default isto create a hierarchy 
that mimics the input files; intermediate di rectories are created asneeded. For example the input filecomp/sources/unix/ 

2211 {arti de 2211 in thenewsgroup comp.sources.unix) iSCOpied tO /news/spool/news.archive/comp/sources/unix/ 

2211. If the-f flag isused, then ali directory namesareflattened out, replacing the slashes with periods. In thiscase, the fi le 

ÌS Copi ed tO /news /spool /news. archive/ comp . sources .unix/ 221 1. 

If the -i flag isused, then archive appendsonelineto the specified index fi le for each article that it copies. This line 
contains the desti nation nameand theM essage-ID and Subject headers. 

For example, a typi cai newsfeeds(5) entry to archive mostsourcenewsgroupsisasfollows: 

source-archive\ 

: !*,*sources*, !*wanted*, !*.d\ 

:Tc,Wn\ 

: /archive -f -i \ 

/usr/ spool/ news /news . archive /INDEX 

Filesarecopied by making a link. If that fai Is, a new file is created. If the-m flag isused, then thefileiscopied to the 
desti nation, and the input fileisreplaced with asymbolic link pointingto the new file. The -m flag isignored. 

By default, archive sets its standard errar to /var/iog/news/erriog.To suppress this redirection, use the -r flag. 

If the input isexhausted, archive exitswith azero status. If an I/O errar occurs, it triesto spool its input, copying it to a file. 
If therewas no input fi lename, the standard input iscopied to /news/spooi/out.going/archive and the program exits. If 
an input fi lename was given, atemporary fi le named input, beh (if input i san absolute pathname) or / news /spool/ 
out.going/input.bch (if the filmarne does not begin with aslash) iscreated. Oncetheinput iscopied, archi ve triesto 
renarne this temporary file to be thenameof the input fileand then exits. 



HIST0RY 

Written by Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
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SEEALSO 

newsf eeds(5) 



arp 



arp— M anipulate the system ARP cache. 
SYNOPSIS 

arp [ -v] [ -t t ype ] -a [host name ] 

arp [ -v] -d host nane ... 

arp [-v] [-t type] -s hostname h w_ a d d r 

arp [ -v] -f f i I ename 

DESCRIPTION 

arp manipulatesthekemel'sARP cache in vari ousways. The primary options are clearing an address mapping entry and 
manually setti ng up one For debugging purposes, the arp program also allows a complete dump of the ARP cache. 

OPTIONS 

-v Teli the user what isgoing on by bei ng verbose. 

-t type When setting or reading theARP cache thisoptional parametertellsarpwhich class 

of entri es it should check for. The default valueof thisparameter isether (hardware 
code 0x01 for IEEE 802.3 10M bps Ethernet). Other values might include network 
technologiessuch asARCnet (a rcnet), PRO net (pronet), and AX.25 (ax25). 

-a [hostname] Shows the entri es of the specified hosts. If the hos t n a me parameter is not used, ali 

entri es are di splay ed. 

-d hostname Remove the entries of the specified host. Thiscan beused if theindicated host is 

brought down, for example 

-s hostname hw_addr M anually create an ARP address mapping entry for host hos t na me with hardware 

address set to h w_ ad d r . T heformat of the hardware address is dependent on the 
hardware class, but for most classes, you can assumethat theusual presentation can 
beused. For the Ethernet class, this issix bytesin hexadecimal, separated by colons. 

-f fi i ename Similar to the -s option, only thistimetheaddressinfo istaken from filef m ename. 

Thiscan beused if ARP entries for a lot of hosts haveto be set up. The name of the 
data file isoften /etc/ethers, but this is not officiai. 
The format of the fi le is si m pie it only contai ns ASC II text lineswith a hostname 
and a hardware address separated by whitespace. 

In ali placeswhere a hostname isexpected, you can also enter an IP address in dotted-decimal notati on. 
FILES 

/proc/net/arp 
/etc/ethers 

AUTHOR 

Fred N . van Kempen (waltjeiauwalt.nl.mugnet.org) 



09 J une 1994 
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badblocks 

badbiocks— Search a device forbad blocks. 
SYNOPSIS 

badblocks [ -b b I o c k - s i z e ] [ -o output_file ] [ -v ] [ -w ] devi ce b I oc ks ■ c ou nt 

D ESC RIPTIO N 

badbiocks isused to search for bad blocks on a device (usuai ly a disk parti ti on). device is the special filecorresponding to the 
device (such as/dev/hdxx). biocks-count isthenumber of blocks on the device. 

OPTIONS 

-b b i o c k - si z e Specify thesize of blocks in bytes. 

-o output.fi i e Write the list of bad blocks to thespecified file. Without thisoption, badbiocks 

displays the list on its standard output, 
-v Verbose mode. 

-w Usewrite-modetest. With thisoption, badbiocks scansfor bad blocks bywriting 

some patterns (Oxaa, 0x55, Oxff, and 0x00) on every block of the device, reading 
every block and compari ng the contents. 

WARNING 

N ever use the -w option on a devi ce contai ni ng an existingfilesystem. Thisoption erasesdata! 
AUTHOR 

badbiocks waswritten by Remy Card (card@masi.ibp.fr), thedeveloper and maintainer of theext2 fs. 
BUGS 

I had no chance to makereal testsof this program becausel use ID E drives, which remap bad blocks. I only madesometests 
on floppies. 

AVAILABILITY 

badblocks i S avai lable for anonymOUS FTP from ftp. ibp.fr and tsx-1 1 .mit.edu in / pub/ linux/ packages/ext2fs. 

SEEALSO 

e2fsck(8), mke2f s(8) 

Version 0.5b, N ovember 1994 
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buffchan— Buffered fi le-wri ti ng back end for InterN etN ews. 
SYNOPSIS 

buffchan [ - b ] [ - c I i n e s ][-C seconds ][-d directory ] 
[-ffields ][-mmap ][-p pidfile ] [ - 1 I i n e s ][-L seconds ] 
[ - r ] [ - s fileformat ] [ - u ] 

DESCRIPTION 

buffchan reads linesfrom standard input and copies certain fields in each lineinto files named by other fields within the 
line buffchan isintended to becalled by innd(8) asan exploder feed. 
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buffchan input is interpreted asaset of lines. Each line contai ns a fixed number of ini ti al fields, followed by a variable 
number of fi lename fields. Ali fields in a line are separated by whitespace. The default number of ini ti al fields isone; the-f 
flag may beused to speci fy adifferent number of fields. Seefiiechan(8) for an example. 

After the ini ti al fields, each remai ni ngfield namesafileto write The -s flag may beused to specify a format stri ngthat maps 
thefield to afilename. Thisisasprintf(3) format stri ng, which should haveasingle%s parameterthat isgiven thefield. 
The default valueis /news/spooi/out.going/%s. Seethedescription of this flag in fiiechan(8). The -d flag may beused to 
specify a directory the program should changeto befo re starti ng. If this flag isused, then the default for the -s flag is 
changed to beasimple%s. 

Once buffchan opens a file, it keepsit open. The input must thereforenever specify morefilesthan the number of available 
descriptorscan keep open. If the -b flag isused, the program will al locate a buffer and attach itto the fi le usi ng setbuf(3). If 
the -u flag isused, the program will request unbuffered output. 

If the -ì flag isused with a number n, then buffchan will cali ffiusn(3) after every n lines are written to a file. If the -c flag 
isused with a number n, then buffchan will dose, and reopen, a file after every n lines are written to a file. 

If the -l flag isused with a number n, then ali fi les will beflushed every n seconds. Similarly, the -c flag may beused to 
specify that ali fi les should beclosed and reopened every n seconds. 

By default, the program setsits standard errar to / var/ log /news /erriog. To suppress this redirection, use the -r flag. 

If the -p flag isused, the program will write a li ne contai ni ng itsprocessID (in text) to the specified file. 

buffchan can beinvoked asan exploder feed (seenewsfeeds(5)). Assuch, if a linestartswith an exclamation point, it is 
treatedasacommand.Therearethreecommands: 

fiush Thefiush command closesand reopensall open fi les; fiush x xx flushesonly the 

specified site. These are analogousto thectiinnd(8) fiush command and can be 
achieved by doinga send fiush xx x command. Applications can teli that the fiush 
hascompleted by renam ing the fi le before issuing the command; buffchan has 
completed the command when the originai filmarne reappears. 
buffchan also changes the access permissionsof the file from read-only for everyone 
to read-writefor owner and group asit flushesor closeseach output file. It changes 
the modes back to read-only if it reopens the samefile. 

drop The drop command issimilarto thefiush command except that any filesarenot 

reopened. If given an argument, then the specified site is dropped; otherwise, ali sites 
aredropped. (Note that the site will berestarted iftheinput stream mentionsthe 
site.) When a ctiinnd "drop site" command issent, innd will automatically forward 
thecommand to buffchan if thesiteisafunnel thatfeeds into this exploder. To 
drop ali Sites, use the ctiinnd send buffchan-site dropcommand. 

readmap Themap file (specified with the-m flag) isreloaded. 

HI STORY 

Written by Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEE ALSO 

ctlinnd(8), f ilechan(8), innd(8), newsf eeds(5). 

cfdisk 

cfdisk— Curses-based disk partition table mani pulator for Linux. 
SYNOPSIS 



cfdisk [ -avz ] [ -c cylinders ][-h h e a d s ][-s sectors-per-track ][-P opt ] 
[devi ce ] 
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DESCRIVO N 

cfdisk isacurses-based program for partitioning a hard disk drive. The devi ce can beany oneof thefollowing: 

/dev/hda [default] 

/dev/hdb 

/dev/sda 

/dev/sdb 

/dev/sdc 

/dev/sdd 

cfdisk first tri esto read thegeometryof the hard disk. If itfails, an errar messageisdisplayed and cfdisk exits. Thisshould 
only happen when partitioning a SCSI drive on an adapter without a BIOS. To correct thisproblem, you can set the 
cylinders, heads, and sectors-per-track on thecommand line. N ext, cfdisk tri esto read thecurrent partition tablefrom the 
disk drive If it isunableto fi gureout the partition table, an errar isdisplayed and the program exits. This mi ghtalso be 
caused by i n correct geo metry information and can beoverridden on thecommand line. Anotherway around thisproblem is 
with the -z option. T hi s wi II ignorethe partition tableon thedisk. 

Themain display iscomposed of foursections, from topto bottom: theheader, the parti ti ons, thecommand line, and a 
warning line. Theheader contains the program nameand version numberfollowed by thedisk drive and itsgeometry. The 
parti ti ons section alwaysdisplays thecurrent partition table. Thecommand lineisthe place where commands and textare 
entered. The available commands are usually displayed in brackets. The warning line is usuai ly empty except when thereis 
important information to be displayed. Thecurrent partition ishighlighted with reverse video (or an arrow if the - a option 
isgiven). Ali partiti on-specific commands apply to thecurrent partition. 

T he format of the partition table in the parti ti on's section is, from left to right: N ame, Flags, Partition Type, Filesystem 
Type, and Size. The nameis the partition devi cenarne. The flags can beBoot, which designates a bootable partition or N C, 
which stands for "N ot Compati ble with DOSorOS/2." DOS, OS/2, and possi bly other operati ng systems requi re the first 
sectorof the first partition on thedisk and ali logicai partitionsto begin on thesecond head. This wastes the second through 
thelast sector of the first track of the first head (the first sector istaken by the partition table itself). cfdisk allowsyou to 
recover these "lost" sectorswith the maxi mizecommand (m). N otethat fdisk(8) and someearly versi ons of DOS create ali 
partitionswith thenumberof serto rs al ready maximized. For more information, see the maxi mizecommand later in this 
chapter. The partition type can beprimary or Logicai. For unallocated space on the drive, the partition type can also be 
Pri/Log or empty (if the space isunusable). The filesystem type section di spi ays the nameof the filesystem used on the 
partition, if known. If it isunknown, then Unknown and thehex valueof the filesystem type are displayed. A special case 
occurswhen there aresectionsof thedisk drivethat cannot beused (because ali theprimary partiti ons are used). When this 
isdetected, thefilesystem type isdisplayed asunusabie. Thesizefield displays the size of the partition in megabytes(by 
default). It can also display the size in sectorsand cylinders (see the change uni tscommand later in this chapter). If an 
asterisks (*) appears after the size, this meansthat the partition isnot aligned on cylinder boundaries. 

DOS 6.X WARNING 

TheDOS 6.x format command looksfor some information in the first sectorof the data area of the partition and treatsthis 
information asmorereliablethan the information in the partition table. dos format expectSDos fdisk to clear the first 512 
bytesof the data area of a partition whenever a size change occurs. dos format looksat this extra information even if the / u 
flag isgiven; weconsider this a bug in dos format and dos fdisk. 

The bottom lineisthat if you use cfdisk or fdisk to change the size of a DOS partition table entry and then you must also 
usedd to zero the first 512 bytesof that partition beforeusingoos format to format the partition. For example, if you were 
usi ng cfdisk to makea DOS partition table entry for /dev/hdai, then (after exiting fdisk or cfdisk and rebooti ng Linux 
so that the partition table information isvalid), you usethecommand dd if=/dev/zero of=/dev/hdai bs=5i2 count=i to 
zero thefi rst 512 bytesof the partition. 

Beextremely careful if you use the dd command because a small typo can makeall of the data on your disk useless. 

For best results, you should alwaysusean OS-specific partition table program. For example, you should makeDOS 
partitionswith the dos fdisk program and Linux partitionswith the Linux fdisk or Linux cfdisk program. 
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COMMANDS 

cfdisk commandscan beentered by pressing the desi red key (pressing E nter after the command isnotnecessary). H ereisa 
list of theavailablecommands: 

b Toggle bootable flag of thecurrent partition. T his allows you to selectwhich primary partition is 

bootableon the drive. 

d Delete thecurrent partition. Thiswill convert thecurrent partition into f ree space and mergeit 

with anyfreespaceimmediately surrounding thecurrent partition. A partition al ready marked as 
free space or marked asunusablecannot bedeleted. 

g Changethedisk geometry (cylinders, heads, orsectors-per-track). Warning: Thisoption should 

only beused by peoplewho know whatthey aredoing. A command-lineoption isalso availableto 
changethedisk geometry. Whileat the change disk geometry command line, you can chooseto 
change cylinders (d), heads (h), and sectors per track (s). The default valuewi II beprinted atthe 
prompt, which you can accept by simply pressing the E nter key or you can exit without changes by 
pressing the Esc key. If you want to change the default value, simply enter the desi red value and 
press E nter. The al tered disk parameter valuesdo not take effect until you return to the mai n menu 
(by pressing E nter or Esc atthe change disk geometry command line If you change the geometry 
such thatthedisk appears larger, the extra sectors are ad d ed attheend of the disk as free space. If 
the disk appears smaller, the parti tions that are beyond the new last sector are deleted and the last 
partition on the drive (or the free space atthe end of thedrive) ismadeto end atthenew last 
sector. 

h Print the help screan. 

m M aximize disk usageof thecurrent partition. T his command will recover the the unused space 

between the partition tableand thebeginning of the partition, atthecost of making the partition 
incompatiblewith DOS, OS/2, and possiblyother operati ngsystems. Thisoption will toggle 
between maximal disk usageand DOS, OS/2, and so on compatibledisk usage. The default when 
creating a partition isto create DOS, OS/2, and so on compatible partitions 

n Create new partitions from free space. If the partition type is Primary or Logicai, a partition of 

that type will becreated, but if the partition type ispri/ Log, you will beprompted forthetypeyou 
want to create. Be aware that there are only four slots available for primary partitions and because 
therecan beonly oneextended partition that contai ns ali of the logicai drives, ali of thelogical 
drives must be conti guous (with no intervening primary partition). cfdisk next promptsyou for 
thesizeof the partition you wantto create. The default size, equal to the enti re free space of the 
current partition, isdisplayed in megabytes. You can either press the E nter key to accept the default 
size or enter a different size atthe prompt. cfdisk acceptssizeentriesin megabytes (m) (default), 
kilobytes (k), cylinders (d), and sectors(s) when you enter thenumber immediately followed by m, 
k, c, or s. If the partition fills the free space available, the partition iscreated and you arereturned 
to themain command line. Otherwise, the partition can becreated at thebeginning or theend of 
the free space, and cfdisk will ask you to choosewhereto place the partition. After the partition is 
created, cfdisk automatically adjusts the other partition's partition typesif ali of the primary 
partitions are used. 

p Print the partition tableto thescreen or to a fi le. There are several different formats for the 

partition that you can choosefrom: 
r Raw data format (exactly whatwould bewritten to disk), 

s Partition table in sector order format. 

t Partition table in raw format. T he raw data format will print the sectors that would bewritten to 

disk if awrite command isselected. First, the primary partition table is printed, followed by the 
partition tables associated with each logicai partition. The data is printed in hex byte- by- byte with 
16 bytes per line. The partition table in sector order format will print the partition table ordered by 
sector number. Thefields, from left to right, are thenumber of the partition, the partition type, the 
first sector, the last sector, the offset from the first sector of the partition to the start of the data, the 
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length of the partition, thefilesystem type (with thehexvaluein parentheses), and the flags (with 
thehex valuein parentheses). In addi ti on to theprimary and logicai parti ti ons, f ree and unusable 
space isprinted and theextended partition isprinted before the first logicai partition. 
If a partition does not start or end on acylinder boundary or if the partition length is not divi si ble 
by thecylinder size, an asterisk (*) isprinted after the non-ali gned sector number/count. This 
usually indicatesthat a partition wascreated by an operati ng system that either does not ali gn 
parti tionsto cylinder boundariesorthat used different disk geometry information. If you know the 
disk geometry of theother operating system, you can enter the geometry information with the 
change geometry command (g). 

For the first partition on the disk and forali logicai partitions, if the offset from thebeginning of 
the partition isnot equal to thenumber of sectors per track (that is, the data does not start on the 
first head), anumber sign (#) isprinted after the offset. For the remaining partitions, if the offset is 
not zero, a number sign isprinted after the offset. This correspondsto the nc flag in the partitions 
section of themain display. 

The partition tablein raw format will print the partition table ordered by partition number. Itwill 
leaveout ali freeand unusable space. The fields, from leftto right, are the number of the partition, 
theflags (in hex), the starting head, sector, and cylinder, thefilesystem ID (in hex), the ending 
head, sector, and cylinder, the starting sector in the partition, and thenumber of sectors in the 
partition. The information in thistablecan be di recti y tran si ated to theraw data format. The 
partition table entri esonly havelO bits available to represent the starting and ending cylinders. 
Thus, when the abso Iute starting (ending) sector number ison acylinder greater than 1023, the 
maximal valuesfor starting (ending) head, sector, and cylinder are printed. This isthemethod used 
byOS/2, and it fixes the problems associated with OS/2'stdisk rewriting the partition tablewhen 
it isnot in this format. Because Linux and OS/2 use absolute sector counts, thevalues in the 
starting and ending head, sector, and cylinder are not used. 

q Quit program. This will exit the program without writing any data to disk. 

t Change thefilesystem type. By default, new partitions are created as Linux partitions, but because 

cf disk can create parti ti ons for other operating systems, changing the partition type allows you to 
enter thehex valueof thefilesystem you desire. A list of theknown filesystem types is displayed. 
You can type the filesystem typeat theprompt or accept the default filesystem type (Linux). 

u C hange units of the partition size display. Itwill rotate through megabytes, sectors, and cylinders. 

w W ri te partition table to disk (you must enter an uppercasew). Because this mi ght destroy dataon 

the disk, you must either confi rm ordeny thewrite by enteringyes or no. If you enter yes, cfdisk 
will write the partition tableto disk and thetell the kernel to re-read the partition tablefrom the 
disk. The re-readi ng of the partition table works in mostcases, butl haveseen itfail. Don't panie. 
Itwill be correct after you reboot the system. In ali cases, I stili recommend rebooting the system 
just to besafe. 

U p arrow, Down arrow M ovecursorto thepreviousor next partition. Ifthere are more partitions than can be displayed on 
ascreen, you can display the next (previous) set of partitions by moving down (up) at thelast (first) 
partition displayed on thescreen. 

Ctrl+L Redraws thescreen. In casesomething goeswrong and you cannot read anything, you can refresh 

thescreen from themain command line. 

? Print the help screen. 

Ali the commands can beentered with either uppercase or lowercaseletters (except for writes). When in asubmenu orata 
promptto enter afilename, you can hit the E se key to return to themain command line. 



0PTI0NS 



Usean arrow cursor instead of reverse video for highlighting thecurrent partition. 
Print the versi on number and copyright. 
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Start with zeroed partition table. Thisoption isuseful when you want to repartition 
your enti re disk. N otethat thisoption does not zero the partition table on the disk; 
rather, it simply starts the program without reading theexisting partition table. 



-c cyl i nders 
-h h e a d s 



-s sectors- per-t rack 0 verri de the number of cyli nders, heads, and sectors-per-track read from the BIOS. If 

your BIOS or adapter does not supply thisinformation or if it supplies incorrect 
information, usetheseoptionsto set the disk geometry values. 

-p opt P ri nts the partition tablein specified formats. opt can beone or more ofr, s, or t. See 

theprmt command for more information on theprint formats. 

SEEALSO 

fdisk(8) 

BUGS 

Thecurrent versi on does not support multiple disks (future additi on). 
AUTHOR 

Kevin E. M artin (martin@cs.unc.edu) 

TheBOGU S Linux Releas, 3 J une 1995 

chat 

chat— Automated conversational script with a modem. 
SYNOPSIS 

chat [ opt i ons ] script 

D ESC RIFTIO N 

The chat program defines a conversational exchangebetween the computer and the modem. Its primary purposeisto 
establish the connection between the Point-to-Point protocol daemon (pppd) and the remote's pppd process. 

OPTIONS 

-t <chat fiie> Read the chat script from the chat file T he use of this option is mutually exclusive with 

the chat script parameters. The user must haveread access to the file M ultiple linesare 
permitted in thefile Space or horizontal tab characters should beused to separate the 
stri ngs. 

-t <t i meo ut > Set thetime-outfortheexpected stri ng to bereceived. If the stri ng isnot received 

within thetimelimit, then the reply stri ng isnotsent. An alternate reply may besent or 
the seri pt wi II fail ifthereisno alternate reply stri ng. A failed script will cause the chat 
program to terminate with a nonzero error code. 

-r <report fiie> Set thefilefor output of the report strings. If you use the keyword report, the resulting 

stri ngs are written to thisfile. If thisoption isnot used and you stili use report 
keywords, the stderr file isused for the report strings. 

-v Request thatthechat script beexecuted in a verbose mode. The chat program will then 

log ali text received from the modem and the output stri ngs that it sendsto thesYSLOG. 
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-v Request thatthechat script beexecuted in a stderr verbose mode. The chat program 

will then log ali textreceived fromthemodem and the output stri ngsthatitsendsto the 
stderr device. T hi s devi ce isusually the locai console at the station runningthechator 
pppd program. Thisoption does notwork properly if the stderr isredirected to the / 
dev/nuii location becausein that case pppd should run in thedetached mode. In that 
case, use the -v option to record thesession on thesYSLOG device. 

script If the script isnotspecified in a file with the -f option, then the seri pt isincluded as 

parametersto the chat program. 

CHAT SCRIPT 

The chat script defines the Communications. 

A script consistsof oneor more"expect-send" pai rsof stri ngs, separated by spaces.with an optional "subexpect-subsend" 
string pair, separated by adash asin thefollowing example: 

ogin: -BREAK-ogin : ppp ssword: hello2u2 

This line indicates that thechat program should expect the string ogin:. If itfailsto receivea login promptwithin the ti me 
interval allotted, it isto send a break sequenceto the remote and then expect the string ogin:. If the first ogin: isreceived, 
then the break sequence is not generated. 

Onceit receives the login prompt, thechat program will send the string ppp and then expect the prompt ssword:. When it 
receives the promptfor the password, itwill send the password neiio2u2. 

A carri age return isusually sent following the reply string. It isnot expected in the "expect" string unless it is specificai ly 
requested by using the nr character sequence. 

The expect sequence should contai n only what isneeded to identify the string. Becauseit isusually stored on a disk file, it 
should notcontain variableinformation. It isgenerally notacceptableto look forti me stri ngs, network identification strings, 
or other vari abl e pi eces of datasuch asan expect string. 

To hdp correct for charactersthat may becorrupted duri ng the initial sequence, look for the string ogin: rather than 
login:. It is possiblethat the leading 1 character might bereceived in errar and you might never find the string even though 
it wassent by the system. For this reason, scripts look for ogin: rather than login: and ssword: rather than password:. 

A very si mple script might look likethis: 

ogin: ppp ssword: hello2u2 

In other words, expect ogin:, send ppp, expect . . .ssword:, send neiio2u2. 

In actual practice, simple scripts are rare. At thevary least, you should include subexpect sequencesin case the originai string 
isnotreceived. For example, consider thefollowing script: 

ogin:-ogin: ppp ssword: hello2u2 

Thisisa better script than thesimpleoneused earlier. This looks for the sameiogin: prompt; however, if onewasnot 
received, a single return sequence is sent and then itwill look for login: again. Should line noiseobscure the first login 
prompt then sendingtheempty linewill usually generate a login prompt again. 

ABORT STRINGS 

M any modemswill report the status of the cali as a string. These strings may becoNNECTEDor no carrier or busy. It is 
often desirableto termi nate the script if the modem fai Isto connect to the remote. The difficulty is that a script does not 
know exactly which modem string it might recei ve On oneattempt, it might recei ve busy, but thenext ti me, it might 
receiveNo carrier. 

These "abort" strings can bespecified in the script using the abort sequence. It iswritten in the script as in thefollowing 
example: 

ABORT BUSY ABORT 'NO CARRIER 1 " ATZ OK ATDT5551212 CONNECT 




Thissequence will expect nothing and then send the stri ng ATZ. Theexpected responseto thisis the stri ngox. W hen it 
receivesoK, the stri ng atdtsssi 21 2 di als the telephone. Theexpected stri ng ìsconnect. If the stri ng connect is recéved, the 
remainder of the script isexecuted. H owever, if the modem fi nds a busy telephone, it sends the stri ng busy. Thiscauses the 
stri ng to match theabort character sequence. The script then fails becauseitfound a match to the abort stri ng. If it recéved 
thestring no carrier, itabortsforthesamereason. Either string may be received. E ither stri ng will termi nate the chat 
script. 

REPORT STRING S 

A reportstringissimilartotheABORT string. The differenceis that the stri ngs and ali charactersto the next control character 
such as a carri age return, arewritten to the report file. 

Thereport stri ngs may beused to isolate the transmission rate of the modem 's connect string and return thevalueto the chat 
user. The analysisof thereport string logie occursin conjunction with the other string processi ng such aslookingforthe 
expect string. The use of the same string for a report and abort sequence isprobably not very useful; however, it ispossible. 

The report stri ngs do not change the completi on code of the program. 

These "report" stri ngs may bespecified in the script usi ng the report sequence. It iswritten in the script as in thefollowing 
example: 

REPORT CONNECT ABORT BUSY " ATDT5551212 CONNECT " ogin: account 

This sequence expeets nothing and then sends the string atdtsssi 212 to dial the telephone. Theexpected string ìsconnect. 
If thestring connect is received, the remainder of the seri pt isexecuted. In addition, the program writesto the expect-file the 
string connect plus anycharacters that follow it such as the connection rate. 

TIME-OUT 

Theinitial time-out valueiS45 seconds. This may bechanged usi ng the -t parameter. 

To change the ti me-out value for the next expect string, thefollowing example may beused: 

ATZ 0K ATDT5551212 CONNECT TIMEOUT 10 ogìn:-ogin: TIMEOUT 5 password:: hello2u2 

T hischanges the ti me-out to 10 seconds when it expeets the ìogin: prompt. The ti me-out isthen changed to 5 seconds 
when it looks for the password prompt. 

Thetime-out, once changed, remai ns i n effect until itischanged again. 
SENDING EOT 

The special reply string of eot indicates that the chat program should send an eot character to the remote. This is usuai ly the 
E nd-of-fi le character sequence. A return character isnot sent following the eot. The eot sequence may beembedded into the 
send stringusingthesequence-D. 

GEN ERATING BREAK 

The special reply string of break causesa break condition to be sent. The break is a special signal on the tran smitter. The 
normal processing on thereceiver isto change the transmission rate. It may beused to cyclethrough the avai labi e transmis- 
sion rateson the remote until you areableto receive a valid login prompt. The break sequence may beembedded into the 
send string using the \k sequence 

ESCAPE SEQUEN CES 

The expect and reply stri ngs may contai n escape sequences. Ali the sequences are legai in the reply string. M any are legai in 
the expect. Those that are not valid in the expect sequence are so indicated. 

Expeets or sends a nuli string. If you send a nuli string, it will stili send the return 
character. T his sequence may either be a pai r of apostrophe or quote characters. 
\\b Represents a backspace character. 
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\\c Suppressesthenewlineat the end of thereply stri ng. T hi s istheonly method to send a 

stri ng without a trai li ng return character. It must beat the end of the send stri ng. For 
example, thesequencetieiio\c will simply send thecharactersh, e, 1, 1, o. (N ot valid in 
expect.) 

\\d Delay for onesecond. The program usessieep(l), which will delay to a maximum of 

onesecond. (N ot valid in expect.) 
\\k InsertaBREAK. (Notvalid in expect.) 

\\n Send a newl ine or li nefeed character. 

un Send a nuli character. The samesequencemay be represented by \a. (N ot valid in 

expect.) 

Up Pauseforafraction ofasecond. Thedelay isonetenth of asecond. (Notvalid in 

expect.) 

\\q Suppresswriting the stri ngto thesYSLOG file. The stri ng ?????? iswritten to the log in 

its place (Notvalid in expect.) 
\\r Send or expect a carriage return. 

\\s Represents a space character in the stri ng. Thismay beused when it isnot desi rable to 

quote the stri ngs that contai ns spaces. The sequence hi tim and hi \stim are the same. 
ut Sendorexpectatabch aracter. 

\\\\ Send or expect a backslash character. 

\\ddd Collapsetheoctal digits(ddd) into a singleASC 1 1 character and send that character. 

(Somecharacters are notvalid in expect.) 
-e Substitutethesequencewith thecontrol character represented byc. For example, the 

character dci (17) isshown as "q. (Somecharacters arenot valid in expect.) 

TERMINATICI CODES 

The chat program will terminate with thefollowing completion codes: 

0 Thenormal termination of the program. Thisindicates that the script wasexecuted 

without errar to the normal conci usion. 

1 Oneormoreof theparametersareinvalid oran expect stri ng was too largeforthe 

internai buffers. This indicatesthat the program as not properly executed. 

2 An errar occurred duri ng the execution of the program. Thismay bedueto aread or 

writeoperation failingfor somereason or chat recavi ng a signal such assiGiNT. 

3 A time-outevent occurred when therewasan expect stri ng without havinga -subsend 

stri ng. Thismay mean that you did not program the script correctly for thecondition or 
that someunexpected event occurred and theexpected stri ng could not befound. 

4 Thefirst stri ng marked asan abort condition occurred. 

5 Thesecond stri ng marked asan abort condition occurred. 

6 Thethird stri ng marked asan abort condition occurred. 

7 Thefourth stri ng marked asan abort condition occurred. 

The other termination codes are also stri ngs marked asan abort condition. 

U si ng the termination code it is possi bleto determi ne which event termi nated the script. It is possi bleto decide if the stri ng 
busy was received from the modem asopposed to no dial tone. Although thefirst event may beretried, thesecond will 
probably have little chance of succeeding during a retry. 

SEE ALSO 

Additional informati on about chat seri pts may befound with UU CP documentati on. The chat script was taken from the 
ideas proposed by the seri pts used bytheuucico program. 

uucico(l), uucp(l) 



COPYRIGHT 

The chat program is in public domain. This isnottheGN U public licen se. If it breaks, then you getto keep both pieces. 

ChatVersion 1.9, 5 M ay 1995 



chroot 

chroot— Changeroot directory and execute a program there. 
SYNOPSIS 

chroot directory program [ a r g ... ] 

DESCRIPTION 

chroot changestheroot directory fora processto a new directory executes a program there. 
SEEALSO 

chroot(2) 

AUTHOR 

Rick Sladkey (jrs@world.std.com) 

Linux 0.99, 20 N ovember 1993 

clock 

clock— M anipulatetheCM OS clock. 
SYNOPSIS 

/sbin/clock [ -u ] -r 

/sbin/clock [ -u ] -w 

/sbin/clock [ -u ] -s 

/sbin/clock [ -u ] -a 

DESCRIPTION 

clock mani pulates the CM OS clock in variousways, allowing itto be read orwritten and allowing synchronization between 
theCM OS clock and the kernel's versi on of the system time. 

OPTIONS 

-u IndicatesthattheCM OS clock is set to U ni versai Time, 

-r Read CM OS clock and print the result to stdout. 

-w Write the system timeintotheCM OSclock. 

-s Set the system timefrom theCM OS clock. 

-a Set the system timefrom theCM OS clock, adjusti ng the ti me to correct for systematic 

error and writing it back into theCM OS clock. Thi sopti on usesthefile/etc/adjtime 
to determi ne how the clock changes. 1 1 contai ns three numbers. 
The first number is the correction in secondsper day. (For example, if your clock runs5 
secondsfast each day, the first number should read -5.0.) 
Thesecond number tellswhen clock waslastused in secondssince 1/1/1970. 
The thi rd number is the remai ni ng part of a second that was leftover after the last 
adjustment. 
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Thefollowing instructionsarefrom thesource code: 

1. Createafile /etc/adjtime containing asthefirst and only lineo. 0 0 0.0. 

2. Run clock -auor clock -a, depending on whether your C M 0 S is in U niversal or Locai T ime This updates the 
second number. 

3. Setyoursystem timeusingthedatecommand. 

4. Updateyour CMOS ti meusing clock -wuor clock -w. 

5. Replacethefirst number in /etc/adjtime by your correction. 

6. Putthecommand clock -auor clock -a in your /etc/rc. locai or I et cron(8) start it regularly. 
FILES 

/etc/adjtime 
/etc/rc. locai 

AUTHORS 

V 1.0 C harles H edrick (hedrickiacs . rutgers . edu) Apr 1992 

Vl.l M odified for clock adjustments, Rob H ooft (hooft@chem.ruu.ni) N ov 1992 

V1.2 Patchesby H arald Koenig(koenig@nova. tat.physik.uni-tuebingen.de) applied by 

Rob H OOft (hooft@EMBL - Heidelberg . DE) 0 Ct 1993 

Linux 0.99, 24 Decemberl992 



comsat 

comsat— Biff server 
SYNOPSIS 

comsat 

DESCRIPTION 

comsat is the server processthat receivesreportsof incoming mail and notifiesusersif they requested thisservice. comsat 
receives messageson adatagram port associated with the biff servi ce speci fi cation (seeservices(5) and inetd(8)). Theone- 
li ne messages are of the form 

user ©ma i I box- of f s et 

If the user specified islogged in to the system and the associated terminal hastheowner executebitturned on (by a biff y), 
the offset isused asaseek offset into the appropriate mail box fi le and the first 7 linesor 560 charactersof themessageare 
printed on the user's terminal. Linesthat appear to bepart of themessageheader other than theFrom, To, Date, or Subject 
linesarenot included in thedisplayed message. 

FILES 

/var/run/utmp to find out who's logged on and on what terminals 
SEEALSO 

biff (1), ìnetd(8) 

BUGS 

Themessageheader fi Iteri ng is prone to error. The densi ty of theinformation presented is near the theoreti cai minimum. 
Usersshould benotified of mail that arriveson other machinesthan theoneto which they arecurrently logged in. 
The noti fi cation should appear in a separate window so it does not messup thescreen. 
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HI STORY 

Thecommand appeared in BSD 4.2. 

BSD 4.2, 16 March 1991 

crond 

crond— cron daemon (D illon'sCron). 
SYNOPSIS 

crond [-1#] [-d[#]] [-f] [-b] [-c directory] 

OPTIONS 

crond is a background daemon that parses individuai crontab files and executescommandson behalf of theusers in 
question. 

-il o g i evei Set logging level; default is 8. 

-d[debugi evei ] Set debugging level; default iso. If no level isspecified with the -d option, the default is 

1 . T his option also sets the logging level to 0 and causes crond to run in theforeground. 
-f Run crond in theforeground. 

-b Run crond in the background (the default unless -d isspecified). 

-c directory Specify directory containing crontab files. 

DESCRIPTION 

crond is responsi ble for scanning the crontab files and runningtheir commandsat the appropriate ti me The crontab 
program com munì cates with crond through the cron. update fi le, which residesin thecrontabs directory, usuai ly /var/ 
spooi/cron/crontabs. Thisisaccomplished by appendi ng the fi lenameof themodified or deleted crontab fileto 
cron. update, which crond then picksup to resynchronize or remove its internai representati on of thefile. 

crond hasa number of built-in li m itati onsto reduce the chance ofit being ill-used. Potenti al ly infinite loops duri ng parsi ng 
are dealt with viaafailsafecounter, and user crontabs are generally limited to 256 crontab entries. crontab linesmay not 
belongerthan 1024 characters, includingthenewline. 

Whenever crond must run a job, it first createsa daemon-owned temporary fileo_Exci_ and o_append to storeany output, 
and then it forkosand changes its user and group permissionsto match that of the user the job is being run for. Then, it 
executes /bin/sh -c to run the job. The temporary fi le remai ns under the ownership of the daemon to prevent the user from 
tampering with it. Upon job completion, crond verifies the securenessof the mail file and, if it has been appended to, mails 
to the fileto user. The sendmaii program isrun under the user'sU ID to prevent mail-related security holes. Unlike 
crontab, thecrond program doesnot leavean open descriptorto thefilefortheduration of thejob'sexecution becausethis 
might cause crond to run out of descriptors. When the crontab program allowsa user to edit his crontab, it copiesthe 
crontab to a user-owned file before running the user's preferred editor. The suid crontab program keeps an open 
descriptorto thefile which it later usesto copy thefile back, thereby ensuring the user has not tampered with the fi le type. 

crond always synchronizesto the top of the minute, checki ng the current ti me against the list of possi ble jobs. The list is 
stored such that the scan goesvery quickly, and crond can deal with several thousand entrieswithouttakingany noticeable 
amountof CPU. 

AUTHOR 

M atthew D illon (dillon@apollo.west.oic.com) 



1 May 1994 
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ctlinnd 

ctiinnd— C ontrol the I nterN etN ews daemon. 
SYNOPSIS 

ctlinnd [ -h ] [ - s ] [ - t t i meo ut ] c o mira nd [ a r g u me nt . . . ] 

D ESC RIPTIO N 

ctiinnd sends a message to the control channel of innd(8), the I nterN etN ews server. 

In thenormal modeof behavior, the message issentto the server, which then performstherequested action and sends back a 
reply with atext message and theexit codefor ctiinnd. If theserver successfully performed thecommand, ctiinnd will exit 
with a status of zero and print the reply on standard output. If theserver could not perform thecommand (for example, it 
wastold to remove a newsgroup that doesnot exist), it will direct ctiinnd to exit with a status of one. Thesnutdown, 
xabort, and xexec commandsdo not generate a reply; ctiinnd will alwaysexit silently with a status of zero. If the -sf lag is 
used, then no messagewill beprinted if thecommand wassuccessful. 

The-t flag can beused to specify how long to wait for the reply from theserver. The timeout valuespecifiesthenumber of 
secondsto wait. A valueof zero waitsforever, and a valuelessthan zero indicatesthat no reply is needed. When waitingfor a 
reply, ctiinnd will try every two minutesto seeif theserver is stili running, so it isunlikely that -to will hang. The default 
is -te. 

To seea command summary, use the -n flag. If acommand isincluded when ctiinnd isinvoked with the-n flag, then only 
theusagefor that command will begiven. 

If a largenumber of groups aregoingto becreated or deleted at once, it may bemoreefficient to pause or th rotti e the server 
and edit the active file di rectly. 

T he complete list of commands follows. Note that ali commands have a fixed number of arguments. If a parameter can bean 
empty stri ng, then it is necessary to specify it astwo adjacent quotes(" "). 

addmstMessage- 1 Dar r exp post paths Add an entry to the history database. T his di rects the server to create a 

history line for M essage-ID . The angle brackets are optional, arr , exp, and 
post specify when the article arrived, what itsexpiration dateis, and when it 
wasposted. AH th ree values are a number indicati ng the number of seconds 
sincetheepoch. If thearticledoes not havean Expires header, then exp 
should bezero. paths isthepathnamewithin thenewsspool directory wh ere 
the article is fi led. If the article is cross- posted, then the names should be 
separated bywhitespace and the paths argument should be inside doublé 
quotes. If theserver ispaused or throttled, this command causes it to bri efly 
open the history database 

aiiow reason Remote connections are allowed. T he reason must be the sametext given 

with an earlier reject command or an empty stri ng. 

begin site Begin feeding s i t e . T his will cause the server to rescan thenewsfeeds(5) file 

to find thespecified site and set up a newsfeed for it. If the site al ready exists, 
a "drop" isdonefirst. Thiscommand isforwarded; see below. 

cancei <Hessage-iD> Remove the article with the specified M essage-l D from the locai system. This 

doesnot generate a cancei message. The angle brackets are optional. Ifthe 
server ispaused or throttled, thiscommand causesitto bri efly open the 
history database. 

changegroup group rest T he newsgroup group is changed so that itsfourth field in the activefile 

becomes the value specified by the rest parameter. This may beused to make 
an existing group moderated orunmoderated, for example. 

checkt ne C heck the syntax of the newsfeeds file, and display a message if any errors are 

found. T he details of the errors are reported to sysiog(3). 
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Flush and drop si te from theserver's list of activefeeds. Thiscommand is 
forwarded; seebelow. 

Flush the buffer for the specified si te. Theactionstaken depend on thetype 
of feed the site receives; see newsfeeds(5). Thisisuseful when the site isfed 
by a file and batching isgoing to start. If si tei san empty stri ng, then ali sites 
areflushed and the acti ve fi le and history databasesarealso written out. This 
command is forwarded; seebelow. 

C losethe log and errar log filesand renarne them to nave a .old extension. 
The history database and active fileare also written out. 
Reopen the history database and start accepting arti ci es after a pause or 
throttlecommand. Thereason must either bean empty stri ng or match the 
textthatwasgiven in the earlier pause or throttlecommand. Ifareject 
command wasdone, thiswill also do an allow command if thereason 
matches the textthatwasgiven inthereject. If a reserve command wasdone, 
thiswill also clear the reservation if thereason matches the textthatwasgiven 
in the reserve. N otethat ifonly the history database haschanged whilethe 
server is paused or throttled, it is not necessary to send it a reload command 
before sendi ng it a go command. If the server throttled itself because it 
accumulate^ too many I/O errors, thiscommand will reset the errar count. If 
theserver was not started with the-ny flag, then thiscommand also doesa 
readers command with yes astheflag and reason asthetext. 
Closethesocketon the specified incomi ng c ha n nei . Thisisuseful when an 
incoming connection appearsto behung. 

Print a command summary for ali commands, or just command if specified. 
Pri nt the server's operati ng mode asa multi I ine summary of the parameters 
and operati ng state. 

Print the nameof channel numbernnn orofall channels if it is an empty 
stri ng. 

Create the speci fi ed newsgroup. Ther est parameter should bethefourth 
field asdescribed in active(5); if it isnot an equal sign, only the first letter is 
used.Thecreator should be the nameof the person creati ng the group. If the 
newsgroup already exists, this is equivalent to the changegroup command. 
This isthe only command that hasdefaults. The creator can beomitted and 
will default to the empty stri ng, andtherest parameter can beomitted and 
will default to y. This command can bedone whilethe server is paused or 
throttled; it will update its internai state when a go command issent. This 
command updates the active. times (seeactive(5)) file. 
C hange the command-li ne parameters of the server. The combi nati on of 
defaults makes it possibleto usethetext of theControl header directi y. 
i et ter isthe innd command-l ine opti on to set, and vai ne isthenew value. 
Forexample, i 5 directs the server to allow only five incoming connections. 
To enableor di sable the action of the-n flag, use the letter y or n for the 

vai uè. 

Pause the server so that no incoming arti ci es are accepted. N 0 existing 
connections are closed, but the history database is closed. T his command 
should beused forshort-term locks, such aswhen replaci ng the history fi les. 
If theserver was not started with the-ny flag, then thiscommand also doesa 
readers command with no astheflag and reason asthetext. 
Allow or disallow newsreaders. If f 1 ag startswith the letter n, then 
newsreading isdisallowed by causi ng the server to pass the text as the value of 
thennrpd(8) -r flag. If f 1 ag starts with the letter y and text is either an empty 
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reject reason 
reload what reason 



renumber group 



reserve reason 



rmgroup group 



sentì f e e d t ext . . 
shutdown reason 



signal s i g site 



throttle reason 



trace tem f I ag 



xabort reason 
xexec patri 



stri ng, orthesamestringthatwasused when newsreadingwasdisallowed, 
then newsreading will beallowed. 

Remote connections(thosethatwould not behanded off to nnrpd) are 
rejected, with reason given as the explanati on. 
The server updatesitsin-memory copiesof various confi guration files. what 
identifies what should bereloaded. If it isan empty stri ng or the word ali, 
then everything isreloaded; if it istheword history, then the history 
database isclosed and opened; if it istheword nosts.nntp, then the 
hosts.nntp(5) file isreloaded; if it istheword active or newsfeeds, then 
both theactiveand newsfeeds files are reloaded; if it istheword 

overview.fmt, then theoverview.fmt(5) file ÌS reloaded. Thereason is 

reported to sysiog. Thereisno way to reload the data inn.conf(5) file; the 
server currently only usesthepathnost parameter, so this restri ction should 
not bea probi em. 

Scan the spool directory for the specified newsgroup and update the low- 
watermark in the active fi le. If group isan empty stri ng, then ali newsgroups 
arescanned. 

Thenext pause or throttle command must user eason asitstext. This 
reservation iscleared by givingan empty stri ng for thereason. This 
command isused by programssuch asexpire(8) thatwantto avoid running 
into other instances of each other. 

Rem ove the speci fi ed newsgroup. Thisisdonebyeditingthe active file. The 
spool directory is not touched, and any articles in the group will beexpired 
usi ng the default expiration parameters. U nlikethenewgroup command, this 
command does not update the active. times file. 
Thespecified text issentas a control li ne to the exploder feed. 
The server isshut down, with thespecified reason recorded in the log and 
sentto ali open connections. It isagood ideato send a throttle command 
first. 

Signal si g is sentto thespecified si te, which must beachannel or exploder 
feed. si g can bea numeric signal number ortheword nup, mt, or te™; case 
isnotsignificant. 

Input isth rotti ed so that ali existing connections are closed and new 
connections are rejected. The history database isclosed. Thisshould beused 
forlong-term locks, such aswhen expire is bei ngrun. If the server was not 
started with the -ny flag, then this command also does a readers command 
with no astheflag and reason asthetext. 

Traci ng isturned on or off for the specified i tem . f i a g should start with the 
letter y or n to turn traci ngon or off. If i tem startsas a number, then traci ng 
is set for the speci fi ed mnd channel, which must befor an incomi ng N NTP 
feed. If it starts with the letter i, then general mnd tracing isturned on or off. 
If it starts with the letter n, then future nnrpd's will or will not havethe-t 
flag enabled, as appropriate 

The server logs the specified reason and then invokestheabort(3) routine. 
Theserver gets ready to shut itself down, but instead of exiting, it executes 
thespecified patti with ali of itsoriginal arguments. If path is innd, then / 

news/bin/innd ÌS invoked; if it ÌS inndstart, then / news /bin/inndst art ÌS 

invoked; if it isan empty stri ng, itwill invoke the appropriate program 
dependi ngon whether it was started with the-p flag; any other value isan 
error. 



cvsbug 
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In addition to bang acted upon within theserver, certain commandscan beforwarded to the appropriate chi Id process. If 
the site receivingthecommand isan exploder (such asbuffchan(8)) or it isafunnel thatfeedsinto an exploder, then the 
command can beforwarded. In thiscase, theserver wi II send acommand lineto the exploder that consistsof thectimnd 
command name. If the site funnelsinto an exploder that hasan asterisk (*) in itswflag (seenewsfeed(5)), then the site name 
isappended to the command; otherwise, no argument isappended. 

BUGS 

ctunnd uses the inndcomm(3) library and isthereforelimited to server repliesno larger than 4KB. 
HI STORY 

W ritten by Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

active(5), expire(8), innd(8), inndcomm(3), inn.conf(5), newsf eeds(5), overview.f mt(5) 

ctrlaltdel 

ctnaitdei— Set thefunction of the Ctrl -rAlt-hDel combination. 
SYNOPSIS 

ctrlaltdel hard | soft 

DESCRIVO N 

Based on examination of theiinux/kernei/sys.c code, it isclear that there are two supported functionsthatthe 
Ctrl-tAlt-hD el sequencecan perform: a hard reset, which immediately reboots the computer without calling sync(2) and 
without any other preparation, and a soft reset, which sendsthesiGiNT(interrupt) signal to themit process (thisisalways 
theprocesswith PID 1). If thisoption isused, theimt(8) program mustsupportthisfeature. B ecause there are nowseveral 
imt(8) programsin the Linux community, consult thedocumentation for the versi on thatyou arecurrently using. 

ctrlaltdel ÌSUSUally US8d in the /etc/rc. locai file. 

FILES 

/etc/rc. locai 

SEEALSO 

simpleinit(8), init(8) 

AUTHOR 

Peter Orbaek (poe@daimi.aau.dk) 

Linux 0.99, 25 October 1993 
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cvsbug— Send problem report (PR) about C VS to a centrai support site. 
SYNOPSIS 



cvsbug [ site ][-f probi em- report ][-t mai I - address ][-P ][-L ] 
[--request-i d ] [ -v ] 
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DESCRIPTION 

cvsbug isatool used to submit problem reports(PRs) to a centrai supportate In most cases, the correct site wi II bethe 
default. Thisargument i ndicates the support sitethat is responsi blefor the category of problem involved. Somesites may use 
a locai addressas a default. Site values are defi ned by usingtheaiiases(5). 

cvsbug invokesan editor on a problem report template (after trying to fili in somefieldswith reasonabl e default values). 
When you exit the editor, cvsbug sendsthecompleted form to the Problem Report M anagement System (GN ATS) at a 
centrai support site. At the support site, thePR is assi gned auniquenumber and isstored in the GN ATS database accordi ng 
to its category and submitter ID . GN ATS automati cally replieswith an acknowledgment, citi ng the category and thePR 
number. 

To ensurethat a PR ishandled promptly, it should contain your (unique) submitter ID and oneof the avai lable categories to 
identify the problem area. (Use cvsbug -l to seea list of categories.) 

The cvsbug template at your site should al ready becustomized with your submitter ID (running instali -sia submitter -id 
to accomplish thisispart of the instai lati on proceduresfor cvsbug). If thishasn't been done, seeyour system administrator 
for your submitter ID, or request onefrom your support site by invoking cvsbug - -request-id. If your sitedoesnot 
disti nguish between different user sites, or if you are not affi liated with the support site, usenet forthisfield. 

The more preci se your problem description and the more complete your information, the faster your support team can solve 
your problem s. 

OPTIONS 

-t probi em- report Specify a file (pr obi em- report ) that already contai ns a complete problem report. cvsbug 

sendsthecontents of the file without invoking the editor. If the value for probi em- report 

is-, then cvsbug readsfrom standard input, 
-t mai i - address Change mail addressat the support site for problem reports. Thedefault mal i ■ addr es s is 

theaddress used for the default site. U sethesiteargument ratherthan thisoption in 

nearly ali cases. 

-p Print the form specified by theenvironment variable pr form on standard output. If pr 

form is not set, print the standard blank PR template Nomail issent. 
-l Pri nt the list of available categories. No mail issent. 

- - request-id Sendsmail to thedefault support site, or si te if specified, with a request for your 

submitter ID . If you are not affi liated with site, use a submitter ID of net. 
-v D i splay the cvsbug version number. 

N ote: Use cvsbug to submit problem reports rather than mail them directly. U si ng both the template and cvsbug itself will 
help ensureall necessary information will reach thesupport site. 

ENVIRONMENT 

T he environment variable editor speci fi es the editor to invoke on the template. T he default is vi. 

If theenvironment variable pr form isset, then its value is used asthefilenameof thetemplate for your problem-report 
editing sessi on. You can usethisto start with a parti al ly compi eted form (for example, a form with theidentification fields 
already compi eted). 

HOWTO FILLOUT A PROBLEM REPORT 

Problem reports haveto bein a parti cu lar form so that a program can easily managethem. Pleaseremember thefollowing 
guidelines: 

Describeonly one problem with each problem report. 

Forfollow-up mail, usethesamesubject I i ne as the one in the automati c acknowledgment. It consistsof category, PR 
number, and the originai synopsis li ne. Thisallows the support site to relateseveral mail messagesto a parti cular PR and 
to record them automati cally. 



cvtbatch 



Please try to be as accurate as possi ble in the subject or synopsis line. 

Thesubject and the synopsis line are not confidenti al. Thisisbecauseopen-bugs listsare compi led from them. Avoid 
putti ngconfidential information there 

SeetheGN U Info file cvsbug. info orthedocument Reporting ProblemsWith cvsbug for detailed information on reporti ng 
problems 

H 0 W TO SU BM IT TEST C ASES, CO D E, AN D SO 0 N 

Submitsmall codesampleswith thePR. C ontact the supportate for instructionson submitti ng larger test cases and 
problematic source code. 

FILES 

/tmp/p$$ copy of PR used in editing session 

/tmp/pf $$ copy of empty PR form, for testing purposes 

/tinp/pbad$$ filefor rejected PRs 

EMACS USER INTERFACE 

An EMACS user interface for cvsbug with completi on of field values is part of the cvsbug distribution (invoked with m-x 
cvsbug). Seethefile cvsbug. infoortheASCII file install in thetop-level directory of the distribution for confi guration 
and installation information. The EMACS LISP templatefileiscvsbug-ei.in and is installed as cvsbug. ei. 

IN STALLATIO N AND CO NFIGU RATIO N 

See cvsbug. info orINsTALL for installation instructions. 

SEEALSO 

Reporting Problems U si ng cvsbug (also installed astheGN U Info fi le cvsbug. info). 

gnats(l), query-pr-(l), edit-pr(l), gnats(8), queue-pr(8), at-pr(8), mkcat(8), mkdist(8) 

AUTHORS 

Jeffrey Osier, Brendan Kehoejason Merrill, HeinzG. Seidl (CygnusSupport). 
COPYING 

Copyright(c) 1992, 1993 F ree Software Foundation, Inc. Permission isgranted to makeand distribute verbatim copiesof 
thismanual provided the copyright noticeand this permission noticearepreserved on ali copies. 

Permission isgranted to copy and distribute modifi ed versi onsof thismanual under the conditions for verbatim copying, 
provided that the enti re resulti ngderived work i s di stri buted under the termsof a permission notice identical to thisone. 

Permission isgranted to copy and distri bute translati onsof thismanual into another language, under the above conditions 
for modifi ed versi ons, except that this permission notice may beincluded in trans! ationsapproved by the F ree Software 
Foundation instead of in theoriginal English. 

xVERSIONx, February 1993 

cvtbatch 

cvtbatch— Convert Usenet batch fileto IN N format. 
SYNOPSIS 

cvtbatch [ -w ì t ems ] 
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DESCRIVO N 

cvtbatch reads standard input as a seri esoflines, convertseach line, and writesitto standard output. It isused to convert 
si mplebatchfilesthat contai n just the articlenameto IN N batchfilesthat contai n additional information abouteach arti ci e 

Each line is taken as the pattinarne to a Usenet article. If it is not an absolute pathname, it istaken relati veto the spool 
directory, /news/spooi. (Only the first word of each lineis parsed; anythi ng following whitespace is ignored.) 

The-wflag specifies how each output line should bewritten. Theuems forthisflag should bechosen from thewflag items 
asspecified in newsfeeds(5). They may bechosen from thefollowing set: 

b Sizeof article in bytes 

f Full pathnameof article 

m Article M essage-ID 

n Relative pathnameof article 

If the input file consistsof a seri esof M essage-ID s, then usegrephistory(l) with the-s flag piped into cvtbatch. 
HI STORY 

Written by Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

grephistory(l) newsf eeds(5) 

cytune 

cytune— T une C yelades driver parameters. 
SYNOPSIS 

cytune [-q [-i nterva ]] ([-s vai u e ] | [ - S vaine]) 
[ -g | G] ([-t ti meout ] |[-T ti meo ut ]) tty [tty . . .] 

D ESC RIPTIO N 

cytune queriesand modifies the interaction threshold for the C yelades driver. Each serial lineon a C yelades card hasa 12- 
byte FI FO for input (and another 12-byte FI FO for output). The "threshold" specifies how many input characters must be 
present in the FIFO beforean interruption israised. W hen a C yelades tty isopened, this threshold is set to a default value 
based on baud rate 

Baud T hreshold 

50-4800 10 
9600 8 
19200 4 
38400 2 
57600-150000 1 

If the threshold is set too low, thelargenumberof interruptionscan load the machine and decreaseoverall system through- 
put. If the threshold is set too high, the FIFO buffer can overflow, and characters wi II belost. Slower machines, however, 
may not beableto deal with theinterrupt load and will requi re that the threshold beadjusted upwards. 

If the C yelades driver was compi led with enable monitoring defined, the cytune command can beused with the -q option 
to report interrupts over the monitoring interval and characters transferred over the monitoring interval. It will also report 
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the state of the FI F 0 . T he maxi mum number of characters i n the F I FO when an i nterrupt occurred, the i nstantaneous 
count of characters in the FI FO , and how many characters are now in the FI FO are reported. This output might look like 
this: 

/dev/cubC0: 830 ints, 9130 chars; fifo: 11 threshold, 11 max, 11 now 
166.259866 interrupts/second, 1828.858521 characters/second 

This output indicatesthat for this monitoring period, theinterruptswerealways béng handled within onecharacter ti me 
becausemax never rose above threshold. This isgood, and you can probably run thisway, provided that a large number of 
samples come out this way. You will lose characters if you overrun the FIFO because the Cyclades hardware doesnot seem to 
support theRTS RS-232 signal li ne for hardware flow control from theDCE to the DTE. 

cytune will in query mode produce a summary report when ended with a sigint or when the threshold ortime-out is 
changed. 

T here may be a responsi veness versus throughput tradeoff. T he C yclades card, at the higher speeds, is capable of putti ng a 
very high i nterrupt load on the system. This will reduce the amountof CPU ti me avai lable for other tasks on your system. 
H owever, the ti me it takesto respond to a si ngle character may beincreased if you increase the threshold. This might be 
noticed by monitoring ping(8) timeson a SLIP link controlied by a Cyclades card. If your SLIP link isgenerally used for 
interactivework such asteinet(l), you might wantto leave the threshold low so that characters areresponded to asquickly 
as possi ble. If your SLIP link isgenerally used for fi le transfer, WWW, and the like, setti ng the FIFO to a high valueis likely 
to reduce the load on your system whilenot si gnificantly affecting throughput. Alternative! y, seethe -t or -t optionsto 
adj ust the ti me that the C yclades wai ts before flushi ng its buffer. U ni ts are 5ms. 

If you arerunningamouseon a C yclades porr., it is likely that you want to maintain thethreshold and time-outata low 
value. 

OPTIONS 

-s value Set thecurrent threshold to vai ue characters. N otethat ifthetty isnot being held open 

by another process, thethreshold will be reset on thenext open. Only values between 1 
and 12, inclusive, arepermitted. 

-t value Set thecurrent flush time-out to vai ue units. N otethat ifthetty isnot being held open 

by another process, thethreshold will be reset on thenext open. Only values between 0 
and 255, inclusive, are permitted. Setting value to 0 forces the default, currently 0x20 
(160ms) but soon to be 0x02 (lOms). U nits are 5ms. 

- g G et the current threshold and ti me-out. 

-t value Set the default flush time-out to vai ue units. When thetty isnext opened, this valueis 

used instead of the default. If value is 0, then the value defaults to 0x20 (160ms), soon to 
beox02 (lOms). 

-g G et the default threshold and flush time-out values. 

-q Gather statisticsabout thetty. The results are only vali d if the Cyclades driver hasbeen 

compi led with enable monitoring defined. This is probably not the default, 
-i intervai Statistics will be gathered every i nt er va i seconds. 

BUGS 

If you run two copiesof cytune atthesametimeto report statistics about the same porr., the ints, chars, and max values will 
be reset and not reported correctly. cytune(8) should prevent this but does not. 

AUTHOR 



N ick Simicich (njs@scifi.emi.net), with modifications by Rik Faith (faith@cs. unc.edu) 
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FILES 



/dev/ttyC[0-l 
/dev/cubC[0-l 

SEEALSO 

setserial(8) 



4 M arch 1995 



debugfs 

debugfs— ext2 fi lesystem debugger. 
SYNOPSIS 

debugfs [ [ -w ] d e v i c e ] 

DESCRIPTION 

debugfs is a filesystem debugger. It can beused to examineand change the state ofan ext2 filesystem. device isthe special 
fi le correspondi ng to the device contai ni ng the ext2 fi lesystem (such as /dev/ hdxx). 



OPTIONS 



Specifythat the fi lesystem should beopen in read-writemode. Withoutthisoption, 
the filesystem isopen in read-only mode. 



COMMANDS 

debugfs isan interactive debugger. Itunderstandsanumber of commands: 

ed file 



chroot file 

dose 

Ciri file 

expand_dir, file 

f ind_f ree_block [goal ] 

f ind_f ree_inode [dir [mode]] 

f reeb block 

f reei file 

help 

iname I ri o d e 

initialize devi ce blockslze 

kill_file file 

In s olir ce_f I I e dest _f i I e 

ls [pattinarne] 

Modif y_inode file 

mkdir file 

open [ -w] devi ce 

pwd 

quit 



C lose the currently open filesystem. 

Clear thecontents of the inode correspondi ngto fi i e. 

Expand a directory. 

Find the fi rstfree block, starti ngfrom goal , and allocate it. 
Find afreeinodeand allocate it. 
M ark the block as not allocateci. 
F ree the inode correspondi ngto fi i e. 



Print thefilenamecorrespondingto i no 
Create an ext2 filesystem on devi ce. 
Remove a fi le and deallocate its blocks. 
Create a link. 

Emulate the is(l) command. 

M odify thecontents of the inode correspondi ngto fi i e 

M ake a di rectory. 

Open a filesystem. 

Quit debugfs. 



(currently not implemented). 



rm file Removeafile. 

rmdirfiie Remove a directory. 

setb block M ark the block as allocateci. 

seti file M ark in usetheinodecorrespondingto file 

show_super_stats List the contents of the super block. 

stat file Dump the contents of the inode corresponding to f i i e. 

testb block Test if the block is marked as al located. 

testi file Test if the inode corresponding to fi i e is marked asallocated. 

uniink file Removealink. 

AUTHOR 

debugfs waswritten by TheodoreT'so (tytso@mit.edu). 
SEEALSO 

dumpe2f s(8), e2fsck(8), mke2f s(8) 

Version 0.5b, N ovember 1994 



dip 

dip— D ialup IP connection handler. 

SYNOPSIS 

dip [-tj 

dip [ -ktv] [ -ni mt u ] seri p t f i I e 
dip [ -iv] [user name ] 

DESCRIPTION 

dip handlestheconnections needed for dialup IP links, such asSLIP or PPP. It can handleboth incomingand outgoing 
connections, using password security for incomi ngeonnections. The outgoing connections use the system 'sdiai(3) library 
if available. 

COMMANDMODE 

The first possi ble use of dip isas a stand-alone program to set up an outgoing IP connection. This can bedoneby invoking 
dip with the -t option, which meansenter test mode and, moreprecisely, dumpyou in the command- mode of the dip 
program. You are remi nded of this by the dip> prompt, or, if you also specified the -v debugging fi ag, the dip [nnnn]> 
prompt. Thelatter prompt also displaysthecurrent valueof the global errivi variable, which isused mostly when dip runs 
in script mode. Fortheinteractivemode it can beused to determi ne if the result of the previous command wasokay. 

Thefollowingisasampletaken from a livesession: 

$dip-t 

DIP: Dialup IP Protocol Driver version 3.3.7 (12/13/93) 
Written by Fred N. van Kempen, MicroWalt Corporation. 

DIP>_ 

Themost helpful command in this mode is, of course, theneip command, which should produce an output si mi larto this: 

DIP> help 

DIP knows about the following commands: 
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databits default dial echo flush 
get goto help if init 
mode modem parity print port 
reset send sleep speed stopbits 
terni wait 



DIP>_ 

Ali commands display how they should beused when invoking them with no or invai id arguments. Just experi ment a little to 
get thefeel of it, and havea look at the sample script files, which also usethiscommand language. 

DIALIN MODE 

Thesecond possi bleway of using dip isasa login shell for incoming IP connections, asin dialup SLIP and PPP connections. 
To make integration into theexisting UNIX system aseasy aspossible, dip can be installed as simply as using it as a login 
shell in the system's password fila A sample entry lookslike 

suunet :ij/SMxiTlGVCo: 1004 :10:UUNET:/tmp:/usr/bin/dip -i 

When user suunet logs in, theiogin(l) program sets the home directory to /tmp and executethedip program with the -i 
option, which meansthatdip must run in input mode dip then triesto locate the nameof the logged-in user (thename 
corresponding to itscurrent user ID, as returned by thegetuid(2) system cali) in its database file. An optional single 
argument to the dip program in thismodecan betheusernamethat must beused in thislookup, regardlessof thecurrent 
user ID. 

dip now scansthe /etc/net/diphosts fi le for an entry for the given username. Thisfilecontainslinesof text (much likethe 
standard password file). Theformat lookslike 

# 

# diphosts This file describes a number of name to 

# address mappings for tbe DIP program. It 

# is used to determine wbicb IP address to 

# use for in incoming cali of some user. 
# 

# Versioni 9(#)diphosts 1.00 12/10/92 FvK 
# 

# Autbor: Fred N. van Kempen, 

# <waltje@uwalt.nl.mugnet.org> 
# 

suunet: :uunet . uu. net :UUNET SLIP:SLIP,296 

# End of diphosts. 

The first field of a line identifies the username, which you must match. Thesecond field can contai n an encrypted password. 
If thisfield is non-nuli, the dip program asksfor an external security password, which must match the password in this field. 
T he third field containsthename(or raw IP address) of thehostthat is connetti ng to the system with this link. If a 
hostnameis given, the usuai address resolving process isstarted, usingeitheranameserveroralocal hosts fi le. 

Thefourth field can contain any text; it is not (yet) used by thedip program. In future releases, this info may beused in the 
system log files. Finally, thefifth field of a li ne contai ns a mixtureof comma-separated flags. Possi bleflags are 

slip to indicate you must usethe SLIP protocol. 

pppto indicate you must usethe PPP protocol. 

number, which givestheMTU parameter of this connection. 

After findingthecorrect line, dip puts the terminal line into RAW mode and asks the system networking layer to allocate a 
channel of the desi red protocol. Finally, if thechannel isactivated, itaddsan entry to the system 'sroutingtableto makethe 
connection work. 



dip now goes into an endless loop of sleeping, which continue unti I the connection isphysically aborted (the li ne is 
dropped). Atthattime, dip removes the entry it made in the system 'sroutingtable and releases the protocol channel for 
reuse. Itthen exits, making room for another sessi on. 

DIALOUTMODE 

Thelast way of usi ng dip isas a program that initiatesoutgoing connections. To makelifeeasier for thepeoplewho haveto 
manage links of thistype, dip usesa chat script to set up a link to a remote system. Thisgives the user an enormousamount 
of flexibility when making the connection, which otherwisecould requiremany command-lineoptions. Thepathnameof 
the seri pt to berun isthen given asthesingleargument to dip; the program will automatically check if thefilehasafilename 
ending in a .dip part. Thisisnot mandatory— just a tool to group scriptstogether in a single directory. A script should look 
something likethis: 

# 

# sample.dip Dialup IP connection support program. 

# This file (should show) shows how to use the DIP 

# scripting commands to establish a link to a host. 

# This host runs the 386bsd operating system, and 

# thus can only be used for the "static" addresses. 
# 

# NOTE: We also need an examnple of a script used to 

# connect to a "dynamic" SLIP server, like an Annex 

# terminal server. . . 
# 

# Versioni (?(#)sample.dip 1.30 07/05/93 
# 

# Author: Fred N. van Kempen, <waltje@uWalt.NL.Mugnet.ORG> 
# 

main: 

# First of ali, set up our name for this connection. 

# I ani called "uwalt.hacktic.nl" (== 193.78.33.238) 
get $local uwalt.hacktic.nl 

# Next, set up the other side's name and address. 

# My dialin machine is called 'xs4all.hacktic.nl' (== 193.78.33.42) 
get Sremote xs4all.hacktic.nl 

# Set the desired serial port and speed. 
port cua0 

speed 38400 

# Reset the modem and terminal line. 

# This seems to cause trouble for some people! 
reset 

# Prepare for dialing. 
send ATQ0V1E1X1 

wait OK 2 

if Serrivi != 0 goto error 

dial 555-1234567 

if Serrivi != 0 goto error 

wait CONNECT 60 

if Serrivi != 0 goto error 

# We are connected. Login to the system, 
login : 

sleep 3 

send \r\n\r\n 

wait ogin: 10 

if Serrivi != 0 goto error 
send N0-WAY\n 
wait ord: 5 

if Serrivi != 0 goto error 
send HA-HA\n 
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wait $ 30 

if $errlvl != 0 goto error 
loggedin: 

# We are now logged in. Start the 'sliplogin' program, 

# as this is not automatically done for me. 
send sliplogin\n 

wait SOME-STRING 15 

# Set up the SLIP operating parameters. 
get $mtu 1500 

# Set Destination net/address as type 'default 1 (vice an address). 

# This is used by the 'route' command to set the kernel routing table. 

# Some machines seem to require this be done for SLIP to work properly. 
default 

# Say hello and fire up! 
done: 

print CONNECTED to Sremote with address $rmtip 
mode SLIP 
goto exit 
error: 

print SLIP to Sremote failed. 
exit : 

This seri ptcausesdip to di al up a host, log in, and get a SLIP interface channel going(in thesamemanner aswith incomi ng 
connections). When ali is set up, it si mply goes into the background and waitsfor a hangup (or just a lethal signal), at which 
it hangs up and exits. 

FILES 

/etc/passwd 
/etc/diphosts 

AUTHORS 

Fred N . van Kempen (waltje@uwalt.nl.mugnet.org), Paul M OSSi p (mossip@vizlab.rutgers.edu), JeffU phoff 
(j uphoff @aoc .nrao .edu), J im Seagrave (j es@g rendei .demon . co. uk), 0 laf Kirch (okir@monad .sub.de). 

Versori 3.3.7, 13 December 1993 

dmesg 

dmesg— Print or control the kernel ring buffer. 
SYNOPSIS 

dmesg [ -c ] [ -n I ève ] 

D ESC RIPTIO N 

dmesg isused to examineor control the kernel ring buffer. 

The program helpsusersto print their bootup messages. Instead of copyingthemessages by hand, the user need only 

dmesg > boot . messages 

and mail the boot. messages fileto whoever can debug their problem. 



OPTIONS 

C lear the ring buffer contents after printing. 

Set the leve! atwhich loggingof messagesisdoneto the console. Forexample, -n 1 
prevents ali messages, except panie messages, from appearingon the console. Ali 
levelsof messages are stili written to /proc/kmsg, so sysiogd(8) can stili beused to 
control exactly wh ere kernel messages appear. When the -n option isused, dmesg 
will not print or clear the kernel ring buffer. 

When both optionsareused, only thelast option on thecommand li ne will havean effect. 
SEEALSO 

syslogd(8) 

AUTHOR 

TheodoreTs'O (tytso@athena.mit.edu) 

Linux 0.99, 28 October 1993 

dumpe2fs 

dumpe2fs— Dump filesystem information. 
SYNOPSIS 

dumpe2fs device 

DESCRIPTION 

dumpe2fs prints the super block and blocksgroup information for the filesystem present on device. 
dumpe2fs issimilarto Berkeley'sdumpfs program fortheBSD Fast File System . 

BUGS 

You need to know the physical filesystem structureto understand the output. 
AUTHOR 

dumpe2fs was written by Remy Card (card@inasi.ibp.fr), the deve! oper and maintainer of theext2 fs. 
AVAILABILITY 

dumpe2fs isavailablefor anonymOUS FTP from ftp.ibp.fr and tsx-11 .mit.edu in /pub/linux/packages/ext2fs. 

SEEALSO 

e2fsck(8), mke2f s(8), tune2fs(8) 

Versori 0.5b, N ovember 1994 

e2fsck 

e2f sck— C heck a Linux second extended filesystem. 
SYNOPSIS 

e2fsck [ -panyrdfvtFV ][-b superbi ock ][-B blocksize ] 
[ -1 ! - L badbl ocksfi I e ] device 



-c 

-n I evel 
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DESCRIPTION 

e2fsck isused to check a Linux second extended filesystem. 

devi ce T he special filecorrespondingto the device (such as/dev/hdxx). 

OPTIONS 

-a Thisoption doesthesamethingasthe -p option. It isprovided for backwards 

compati bility only; it issuggested that people use -p option whenever possible. 
-b superbi o c k Instead of using the normal superblock, use the alternative superblock specified by 

superbi ock. 

-B b i o c k s i z e Usually, e2fsck will search for the superblock at variousdifferent block sizesin an 

atterri ptto find the appropriate block si ze. T hi s search can befooled in somecases. 
Thisoption forcese2fsck to only try locati ng the superblock at a particular 
bi ocksi ze. If the superblock isnot found, e2fsck will termi nate with a fatai errar. 

-d Print debugging output (useless unlessyou are debugging e2fsck ). 

-f Force checking even if the filesystem seemsclean. 

-f Flush thefilesystem device's buffer caches before beginning. Only reallyuseful for 

doing e2fsck timetrials. 

-ì fi i e n a me Add the blocks listed in the fi le specified by filmarne to the list of bad blocks. 

- l fi i e n a me Set the bad blocks list to be the list of blocks specified by f i i e n a me . (Thisoption is 

thesameasthe -ì option except the bad blocks list iscleared before the blocks listed 
in thefileareadded to the bad blocks list.) 

-n Open thefilesystem read-only, and assurmean answer of "no" to ali questiona 

Allows e2fsck to beused non-i nteractively. (N ote: if the -ì or -l optionsare 
specified in addition to the -n option, then thefilesystem will beopened read-write 
to permit the bad-blocks list to beupdated. H owever, no other changeswill bemade 
to thefilesystem.) 

-p Automatically repair ("preen") thefilesystem without any questions. 

-r Thisoption doesnothingat ali; it isprovided only for backwards compati bility. 

-t Print timing statisticsfore2fsck. If thisoption isusedtwice, additional timing 

statisti cs areprinted on a pass- by-pass basi s 
-v Verbose mode, 

-v Print version information and exit. 

-y Assume an answer of "yes" to ali questions; allows e2fsck to beused non- 

i nteractively. 

EXIT CODE 

The exit code returned bye2fsck isthesum of thefollowing conditions: 

0 No errors 

1 Filesystem errors corrected 

2 Filesystem errors corrected; system should berebooted if filesystem wasmounted 
4 Filesystem errors left uncorrected 

8 Operational errar 

16 U sage or syntax errar 

128 Shared library error 
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BUGS 

Almost any piece of software will havebugs. If you manageto find a filesystem that causese2fsck to crash, orthate2fsck is 
unableto repair, pleasereport itto theauthor. 

Please include as much informati on as possible in your bug report. Ideally, include a complete transcript of thee2tsck run, 
so I can seeexactly what errar messagesaredisplayed. If you have a writeable filesystem where the transcript can bestored, 
thescript(l) program isa handy way to save the output of e2fsck to a file. 

It i salso useful to send the output of dumpe2fs(8). If aspecific inodeor inodesseemsto begivinge2fsck trouble, try 
runningthedebugfs(8) command and send the output of thestat command run on therelevant inodes. If theinodeisa 
directory, thedebugfs dump command will allow you to extract the contentsof the directory inode, which can sent to me 
after bei ng first run through uuencode(l). 

Always include the full versi on stri ng that e2fsck displayswhen it isrun so I know which version you arerunning. 
AUTHOR 

Thisversion of e2fsck iswritten by TheodoreTs'o (tytso@mit.edu). 
SEEALSO 

mke2f s(8), tune2fs(8), dumpe2f s(8), debugfs(8) 

Version 0.5b, N ovember 1994 



edquota 

edquota— E dit user quotas. 



SYNOPSIS 

/usr/etc/edquota [ -p proto-user ][-ug ] nane... 
/usr/etc/edquota [ -ug ] -t 

DESCRIVO N 

edquota isaquota editor. One or moreusersor groups may bespecified on the command line. For each user or group, a 
temporary file is createci with an ASCII representati on of thecurrent disk quotas for that user or group and an editor isthen 
invoked on the fi le The quotas may then bemodified, new quotas added, and so on. U pon leavingtheeditor, edquota reads 
the temporary file and modifies the binary quota files to reflect the changes made. 

The editor invoked isvì(l) unless the environment vari able specifies otherwise. 

Only thesuperuser may edit quotas. (For quotaste beestablished on a filesystem, the root directory of thefilesystem must 
contain a file, owned by root, called quota. user or quota. group. Seequotaon(8) for detai Is.) 

OPTIONS 

-u Edit the userquota. This is the default, 

-g Edit the groupquota. 

-p D uplicate the quotas of the prototypi cai user specified for each user specified. This is 

thenormal mechanism used to initialize quotas for groups of userà 

-t E dit the soft ti meli mits for each filesystem. If the ti meli mits are zero, the default 

timelimitsin <iinux/quota.h> are used. Timeunitsof sec(onds), min(utes), 
hour(s), day(s), week(s), and month(s) areunderstood. Timelimitsareprinted in the 
greatest possible ti me unit such that the value isgreater than or equal to one 
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FILES 

quota, user or quota. group Q uota fi le at the filesystem root 

/etc/mtab M ounted filesystems 

SEEALSO 

quota(l), vi(l), quotactl(2), quotacheck(8), quotaon(8), repquota(8) 

BUGS 

The format of the temporary file is inscrutable. 

8 Junel993 



expire 

expire— Usenet article and history expiration program. 
SYNOPSIS 

expire [ - d dir ] Q file ] [ - g file ] [ - h file ] 
[-i ][-l ][-n ][-p ][-q ][-r r eas on ][-s ][-t ] 
[-v level ][-w number ][-x ][-z file ] [expire. ctl] 

D ESC RIPTIO N 

expire scansthe history(5) textfile /news/iib/ history and uses the information recorded in it to purgeold newsarticles. 
To speci fy an alternate hi story file, use the -t flag. To specify an alternate input text history file, use the -n flag. expire uses 
the old dbz(3z) database to determi ne the si zeof thenew one. To ignoretheold database, use the -i flag. 

expire usually just unlinks each fileif it should beexpired. If the -1 flag isused, then ali arti ci es after the first onearetreated 
asif they could besymbolic linksto the first one. In thiscase, the first article wi II not beremoved as longasany other cross- 
postsof th e arti ci e rem ai n. 

expire usually sends a pause command to the locai innd(8) daemon when it needsexclusi ve access to the history file using 
the string Expiring asthereason. To giveadifferent reason, use the -r flag. The processi D wi 1 1 beappended to thereason. 
When expire isfinished and thenew history fi lei s ready, it sends ago command. If innd isnot running, use the -n flag and 
expire will not send the pause or go commands. (For moredetailson the commands, seectiinnd(8).) N otethat expire 
only needsexclusi ve access for a very short ti me— long enough to seeif any new arti ci es arri ved sinceit first hit the end of the 
fileand to renamethenewfilesto the working fi les. 

If the -s flag isused, then expire will print a summary when it exits, showing the approxi mate number of kilobytes used by 
ali deleted articles. 

If the-t flag isused, then expire will generate a list of the fi les that should beremoved on its standard output, and thenew 
history fi le will beleft in history. n, history. n. dir, and history. n. pag. This flag isuseful for debugging when used with 
the-n and -s flags. N otethat if the-f flag isused, then thenamespecified with that flag will beused instead of history. 

If the-x flag isused, then expire will not create any new history fi les. This ismost useful when combined with the-n, -s, 
and -t flags to seehow different expiration policieswould changetheamount of disk space used. 

If the-z flag isused, then articles are not removed, but their namesarewritten to the specified file. Seethedescription of 

expirerm in news . daily(8). 

expire makes its decisi onson the ti me the article arri ved, asfound in the history file. This means articles are often kept a 
little longer than with other expiration programsthat base their decisi onson the article's posti ng date. To usethearticle's 
posti ng date, use the -p flag. Use the -w flag to "warp" ti me so that expire thinksit isrunningat some ti me other then the 
current ti me. T he value should be a signed floating-poi nt number of the number of days to use as the offset. 
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If the-d flag isused, then thenew hi story file and database is createci in thespecified directory, dir. This isuseful when the 
filesystem does not havesufficient space to hold both the old and new history files. W hen this flag isused, expire leavesthe 
server paused and creates a zero-length filenamed after thenew history file, with an extension of .done to indicate that it has 
successfully completed theexpiration. T hecalling script should instali thenew history file and unpause the server. The-r 
flagshould beusedwith thisflag. 

If a filename is specified, it istaken as the control file and parsed accordi ngto therulesin expire. cti(5). A single dash (-) 
may beused to read thefilefrom standard input. If no file is specified, thefile / news /ubi expire, cti isread. 

expire usually complainsabout articles that are posted to newsgroups not mentioned in theactivefile. To suppressthis 
action, use the -q flag. 

T he -v flag isused to increasetheverbosityof the program, generati ng messagesto standard output. The level should bea 
number, wherehighernumbersresultin more output. Level onewill print totals of the various actions done{not valid if a 
new history file is not written), level two will print report on each individuai file and level five results in morethan oneline 
of output forevery line processeci. If the-g flag isgiven, then a one-linesummary equivalent to the output of -vi and 
preceded bythecurrenttimewill beappended to thespecified file. 

HISTORY 

W ritten by Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

ctlinnd(8), dbz(3z), expire . ctl(5), history(5), innd(8), inndcomm(3) 



expireover 

expireover— Expire entri esfrom the news overview database 
SYNOPSIS 

expireover [ -a ][-D overviewdir ][-ffile ][-n ] 
[ -0 o v e r v i e w. f mt ][-s ][-v ][-z ][file... ] 

DESCRIPTION 

expireover expires entri es from the news overview database. It readsa list of pathnames (relati veto the spool directory, / 
news /spool) from thespecified fi Ics or standard input if none are specified. (A filenameof - may beused to specify the 
standard input.) It then removesany mention of those articles from the appropriate overview database. If the -z flag isused, 
then the input isassumed to besorted such that ali entries for a newsgroup appear together so that it can bepurged at once. 
Thisflag can beuseful when used with thesorted output of expire(8)'s-z flag. 

If the -s flag isused, then expireover will read the spool directory for ali groups mentioned in theactive(5) fi le and 
rem ove the overview entries for any articles that do not appear. To specify an alternate fi le, use the -f flag; a nameof - is 
taken to mean the standard input. 

The -a flag reads the spool directory and addsany missing overview entries. It will create fi lesif necessary. This can beused 
to initi al ize a database orto sync up a overview database that may be lacking articles due to a crash, overcnan should be 
running, to ensurethat any incoming articles get included. U si ng this flag i mplies the -s flag; the-t flag may beused to add 
only a subset of the newsgroups. 

To seea list of the entries that would beadded or deleted, use the -v flag. To perform no real updates, use the -n flag. 

T he -d flag can beused to specify where the databases are stored. The default directory is/news/spooi. 

T he -o flag may beused to specify an alternate location for the overview. fmt(5) file this is usually only useful for debug- 
ging. 
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HISTORY 

Written by Rob Robertson (rob@vioiet.berkeiey.edu) and Rich $alz (rsaiz@uunet.uu.net) with heìp from Dave 
Laurence (taie@uunet.uu.net) for I nterN etN ews. 

SEEALSO 

expire(8), overview.f mt(5) 

fastrm 

fast™— Q ui ckly remove a set of fi les. 
SYNOPSIS 

fastrm [ -d ][-e ][-uN ][-sH ][-cl ] base_di rectory 

D ESC RIPTIO N 

fast™ readsa list of fi les, oneper line from its standard input and removesthem. If afileisnot an abso Iute pattinarne, it is 
taken relative to the di rectory specified on thecommand line. The base di rectory parameter must bea simple absolute 
pattinarne— that is, it must not contain any / . / or / . ./ references. 

fast™ isdesigned to befasterthan thetypical | xargs ™ pipeline. For example, fast™ will usually cndir(2) into a 
directory before removi ng fi les from it. If the input is sorteci, this meansthat most filesto beremoved will be simple names. 

fast™ assumesthat its input isvalid and that it issafeto just do an uniink(2) cali for each item to beremoved. Asasafety 
measure, if fastrm isrun by root, it will first stat(2) the item to makesurethat it is not a directory before uni inking it. 

If the-d flag isused, then no filesareremoved. Instead, a list of the fi lesto beremoved, in debug form, is printed on the 
standard output. Each li ne contai nseither the current directory of fastrm at the ti me it would do theunlink and then the 
pathnameitwould passto uniink(2) astwo fields separated by wh ite space and a / or the absolute pathname (a single field) 
of filesit would unlink usi ng the absolute pathname. 

If the -e flag isused, fastrm will treat an empty input file (stdin) asan errar. Thisismost useful when fastrm islast in a 
pipeline after a precedi ng sort(l) because if the sort fai Is, therewill usually beno output to become input of fastrm. 

If the-u flag isused, then fastrm makesfurther assumptionsabout itswork environment— in particular, thatthereareno 
symbolic links in the target tree. This flag also suggeststhat it is probably faster to referencethepath ../../../ rather than 
start from the root and come down (note that this probably isn'ttrueon systemsthat havea namei cache, which usually 
holdseverythingexcept . .). The optional n isan integer that specifies the maximum number of . . segmentsto use— paths 
that would use more than this use the absolute pathname (from the root) instead. If the-u flag isgiven without a value, -ui 
isassumed. 

If the -s flag isused, then fastrm will perform the unii nks from one directory— that is, when agroup of fi les in one 
directory appear in the input consecutively— in the order that the fi les appear in the di rectory from which they areto be 
removed. Theintent of this flag isthat on systemsthat havea per- prò cess directory cache, fi nding fi les in the di rectory 
should be faster. It can havesmaller benefitson other systems. The optional m isan integer that specifies the number of fi les 
that must begoingto beremoved from onedi rectory before thefiles will beordered. If the -s flag isgiven without a value, 
-ss isassumed. When the directory reordering is in use, fastrm will avoid attempting to unlink fi les that it can'tseein the 
directory, which can speed it appreciably when many of thefilenameshavealready been removed. 

The-c flag may begiven to instruct fastrm when it should cndir(2). If the number of filesto beunlinked from a directory 
isat least i, then fastrm will cndir and unlink the fi les from in the di rectory. Otherwise, it will build a path relative to its 
current di rectory. If -c isgiven without the optional integer i, then -ci isassumed, which will causetastrmto alwaysuse 
chdir. If -c isnot used at ali, then -c3 isassumed. Use -ce to prevent fastrm from ever using chdir(2). 



fdformat 



1295 



Therearealso -a and -r options, which do nothingat ali except allow you to say fast™ -usa, fast™ -ussr, or fast ™ 
-user. T hese happen to often be convenient sets of options to use. 

fast™ exitswith a status of 0 if therewereno problemsor 1 if somethingwentwrong. Attemptingto removeafilethat does 
not exist is not considered a problem. If the program exitswith a nonzero status, it isprobably agood ideato feed the list of 
filesinto an xargs ™ pipeline. 



fdformat 

fdformat— Low-level formats a floppy disk. 
SYNOPSIS 

fdformat [ -n ] devi ce 

D ESC RIPTIO N 

fdformat does a low-level format on a floppy disk, device isusually oneof thefollowing (for floppy devices, the major is 2, 
and the minor isshown for informational purposesonly): 

/dev/fd0d36B (minor =4) 
/dev/fd0hi2O0 (minor =8) 
/dev/fd0D360 (minor =12) 
/dev/fd0H360 (minor =12) 
/dev/fd0D720 (minor =16) 
/dev/fd0H720 (minor =16) 
/dev/fd0h360 (minor =20) 
/dev/fd0h720 (minor =24) 
/dev/fd0Hi440 (minor =28) 
/dev/fdid360 (minor =5) 
/dev/fdihi200 (minor =9) 
/dev/fdiD360 (minor =13) 
/dev/fdiH360 (minor =13) 
/dev/fdiD720 (minor =17) 
/dev/fdiH720 (minor =17) 
/dev/fdih360 (minor =21) 
/dev/fdih720 (minor =25) 
/dev/fdim440 (minor =29) 

Thegeneric floppy devices, /dev/fdo and /dev/fdi, will fail to work with fdformat when a non-standard format isbeing 
used orif the format hasnot been autodetected earlier. In thiscase, usesetfdp™(8) to load the disk parameters. 

OPTIONS 

-n No verify. Thisoption will disabletheverification that isperformed after the format. 



SEEALSO 

fd(4), setfdprm(8), mkfs(8), emkf s(8) 
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AUTHOR 

W erner Almesberger (almesberianessie . cs . id . ethz . eh) 

Linux 0.99, 1 February 1993 

fdisk 

fdisk— Partition table manipulator for Linux. 
SYNOPSIS 

fdisk [ -1 ] [ -v ] [ -s partition] [ device ] 

DESCRIPTION 

fdisk isa menu-driven program for mani pulation of the hard disk partition table. The devi ce isusually oneof the following: 

/dev/hda 
/dev/hdb 
/dev/sda 
/dev/sdb 

The partition isa device namefollowed by a partition number. Forexample, /dev/hdai is the first partition on the first hard 
disk in the system. 

If possi ble, fdisk wi II obtain the disk geometry automatically. Thisisnot necessari ly the physical disk geometry but isthe 
disk geometry that M S-DOS uses for the partition table. If fdisk warnsyou that you need to set the disk geometry, please 
believethis statement and set the geometry. T hi sshould only benecessary with certain SCSI h o st ad apters ( t h e d ri vers f o r 
which arerapidly bei ng modified to provide geometry information automatically). 

Whenever a partition table isprinted, aconsistency check isperformed on the partition table entries. This check verifies that 
the physical and logicai start and end poi nts are i denti cai and that the partition startsand endson acylinder boundary 
(except for the first partition). 

Old versionsof fdisk (ali versions priorto l.lr including 0.93) incorrectly mapped thecyiinder/head/sector specification 
onto absolute sectors. Thismight result in the first partition on a drive faili ng the consistency check. If you use LI LO to 
boot, thissituation can beignored. H owever, there are reports that the OS/2 boot manager will not boot a partition with 
i neon si stent data. 

Some versionsof M S-DOS create a first partition thatdoes not begin on acylinder boundary but on sector 2 of the first 
cylinder. Partiti ons beginning in cylinder 1 cannot begin on acylinder boundary, but this is unii kely to cause difficulty 
unlessyou haveOS/2 on your machine. 

In version l.lr, a blkrrpart ioctio isperformed beforeexitingwhen the partition table isupdated. Thisis primari ly to 
ensurethat removableSCSI disks havetheir partition table information updated. If the kernel does not update its partition 
table information, fdisk warnsyou to reboot. If you do not rebootyour system after recéving such awarning, you might 
loseor corrupt the data on the disk. Sometimes blkrrpart fai Is si lently; when instali ing Linux, you should always reboot 
after ed i ti n g the parti ti on tabi e. 

DOS 6,X WARNING 

TheDOS 6.x format command looksfor some information in the first sector of the data area of the partition and treatsthis 
information asmore reliablethan the information in the partition table. dos format expeets DOS fdisk to clear the first 
512 bytesof the data area of a partition whenever a sizechangeoccurs. dos format will look at this extra information even if 
the /uflag isgiven 
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Weconsiderthisa bug in dos format and dos fdisk. 

The bottoni lineisthat if you use cfdisk or fdisk to changethesizeof a DOS parti tion table entry, then you must also use 
dd to zero the first 512 bytesof that parti tion beforeusingoos format to format the partition. Forexample, if youwere 
usi ng cfdisk to makea DOS partition table entry for /dev/hdai, then (after exiting fdisk or cfdisk and rebooti ng Linux 
so that the partition table informati on isvalid) you would usethecommand dd if=/dev/zero of=/dev/hdai bs=5i2 
count=i to zero the first 512 bytesof the partition. 

Beextremely careful if you use the dd command becauseasmall typo can makeall of the data on your disk useless. 

For best results, you should alwaysusean OS-specific partition table program. Forexample, you should makeDOS 
parti tionswith the dos fdisk program and Linux parti tionswith the Linux fdisk or Linux cfdisk program. 

OPTIONS 

-v Prints version number of fdisk program. 

-1 ListS the partition tables for /dev/hda, /dev/hdb, /dev/sda, /dev/sdb, /dev/sdc, / 

dev/sdd, /dev/sde, /dev/sdf, /dev/sdg, and /dev/sdh and then exitS. 

-s parti ti on I f the partition is not a D 0 S partition (the partition ID isgreater than 10), then the 

size of that partition isprinted on thestandard output. Thisvalue isusually used as 
an argument to themkfs(8) program to speci fy the size of the partition that wi II be 
formatted. 

BUGS 

Although thisman page(written by faith@cs.unc.edu) ispoor, thereis excel lent documentation in theREADME.fdiskfile 
(written byLeBianc@mcc.ac.uk) that should always bevvi th the fdisk distri bution. If you cannotfind thisfilein the ut u- 
ìinux-* directory orwith the f disk, c source file, then you should writeto the distri butor of your version of fdisk and 
complain that you do not haveall of the available documentation. 

AUTHOR 

A.V. LeBlanc (LeBianc@mcc.ac.uk). vl.Or: SCSI and extfs support added by Rik Faith (faith@cs.unc.edu). vi. Ir: Bug 
fixesand enhancements by Rik Faith (faith@cs.unc.edu), with special thanksto M ichael Bischoff (n041905@ws.rz.tu- 
bs.de or mbi@mo.math.nat.tu-bs.de). vl.3: Latest enhancements and bugfixesbyA.V. LeBlanc, includi ng the addi tion 
of the -soption. v2.0: D iskslargerthan 2GB arenowfully supported, thanksto Remy Card'siiseek support. 

Linux 1.0, 3 Junel995 

filechan 

fiiechan— Fi le-writi ng back end for InterN etN ews. 
SYNOPSIS 

filechan [ -d di r ect or y ] [ - f f i el ds ][-m mapfile ] [ - p pi df i I e ] 

D ESC RIFTIO N 

fiiechan reads li nes from standard input and copies certain fields in each lineinto filesnamed by other fields within the 
line, fiiechan isintended to becalled by innd(8) asachannel feed. (It is not a full exploder and doesnot acceptcommands; 
seenewsfeeds(5) for a descri ption of the difference and buffcnan(8) foran exploder program.) 

fiiechan input is interpreted asaset of li nes. Each linecontainsafixed number of ini ti al fields, followed by a variable 
number of fi lename fields. AH fields in a line are separated by whitespace. The default number of ini ti al fields isone; the-f 
flag may be used to speci fy a different number of fields 
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For each lineof input, fiiechan writes the i nitial fields, separated by whitespaceand followed by a newline, to each of the 
filesnamed in the fi lename fields. W hen writi ng to a fi le, fiiechan opensit in append mode and triesto lock it and change 
theownership to the user and group who owns the directory where the fi le is bei ng written. 

By default, fiiechan writes itsargumentsinto the directory /news /spooi/out.going. The -d flag may beused to specify a 
directory the program should change to befo re starti ng. 

If the -p flag isused, the program will writea li ne contai ni ng itsprocessID (in text) to thespecified file. 
If fiiechan isinvoked with -f 2 and given thefollowing input: 

news/software/b/132 <1643@munnari.oz.au>foo uunet 
news/software/b/133 <102060@litchi.foo.com> uunet munnari 
comp/sources/unix/2002 <999@news . f oo . com>f oo uunet munnari 

Then the file -foo will havetheselines: 

news/software/b/132 <1643@munnari.oz.au> 
comp/sources/unix/2002 <999@news . foo . com> 

Thefilemunnari will have these lines: 

news/software/b/133 <102060@litchi.f oo.com> 
comp/sources/unix/2002 <999@news . foo . com> 

Thefileuunet will havetheselines: 

news/software/b/132 <1643@munnari.oz.au> 
news/software/b/133 <1 02060glitchi.foo.com> 
comp/sources/unix/2002 <999@news . foo . com> 

Becausethetimewindow in which a fi le is open isvery small, complicated flushingand locking protocolsarenot needed; a 
mv(l) followed by asieep(l) foracoupleof secondsissufficient. 

A map file may bespecified by usi ng the -m flag. Blank lines and lines starti ng with anumbersign (#) areignored. Ali other 
lines should havetwo hostnames separated by a colon. The first field isthenamethat may appear in the input stream; the 
second field namesthefileto beused when the name in the first field appears. For example, thefollowing map file may be 
used to map the short namesto the full domain names: 

# This is a comment uunetmews.uu.net foo:foo.com munnari: munnari. oz.au 

HI STORY 

Written by Robert E Iz (kre@munnari.oz.au); flagsadded by Ri Ch $alz (rsalz@uunet.uu.net). 

SEEALSO 

buffchan(8), innd(8), newsfeeds(5) 

fsck 

fsck— Check and repair a Linux fi lesystem. 
SYNOPSIS 



fsck [ -AVRTN ][-s ][-t fstype ][fs-opti ons ] filesys [ ... ] 



fsck 
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DESCRIVO N 

fsck isused to check and opti onally repair a Linux filesystem. fiiesys iseither the device name(such as /dev/hdai or /dev/ 
sdb2) orthemount point (such as /, /usi-, or /home) for the filesystem. If thistsck hasseveral filesystemson different 
physical disk drivesto check, thistsck will try to run them in parallel. Thisreducesthetotal amounttimeittakesto check 
ali of thefilesystems becausetsck takes advantage of the parai lei ism of multiple disk spindles. 

The exit code returned bytsck isthesum of thefollowing conditi ons: 

0 No errors 

1 F i I esystem errors corrected 

2 System should be rebooted 

4 Filesystem errors left uncorrected 

8 Operational error 

16 U sage or syntax error 

128 Shared library error 

The exit code returned when ali filesystemsarechecked usi ng the -Aoption isthe bitwise or of the exit codesfor each file 
system that ischecked. 

In actuality, fsck issimply a front end for the vari ous filesystem checkers(fsck.fstype) available under Linux. The 
filesystem-specific checker issearched for in /sbin first, then in /etc/fs and /etc, and finally in thedirectorieslisted in the 
path environment variable. Please see the filesystem-specific checker manual pages for further details. 



OPTIONS 



-tf stype 



f s -options 



Walk through the /etc/fstab fi le and try to check ali filesystemsin onerun. This 
option istypically used from the /etc/rc system initialization file instead of 
multi pie commands for checking a single fi le system. 

When checking ali filesystemswith the - a flag, skiptheroot filesystem (in caseit's 

already mounted read-write). 

Don'tshow thetitleon startup. 

D on't execute; just show what would be done 

Seri alize fsck operati ons. Thisisagood idea if you checking multi pie filesystemsin 
and thecheckersarein an interactivemode (N ote e2fsck runsin an interattive 
mode by default. To makee2fsck run in a non-i nteracti ve mode, you must either 
specify the -p or -a option, if you want errorsto be corrected automati cai ly, orthe - 
n option if you do not.) 

Produce verbose output, includi ng ali filesystem-specific commands that are 
executed. 

Specifies the typeof filesystem to bechecked. When the -a flag isspecified, only 

fi lesystems that match f stype arechecked. If f stype isprefixed with no, only 

fi lesystemswhose filesystem do not match fstype arechecked. 

Usually, the filesystem typeisdeduced by searching forf i esys in the / etc/fstab 

fi le and usi ng the corresponding entry. If the type can not bededuced, fsck will use 

thetypespecified by the -t option if it specifiesaunique filesystem type. If thistype 

is not available, the the default filesystem type (currently ext2) isused. 

Any options that are not understood by fsck, or thatfollow the - option aretreated 

as filesystem-specific optionsto be passed to the filesystem-specific checker. 
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Currently, standardized filesystem-specific optionsaresomewhat in flux. Although notguaranteed, thefollowing options are 
supported by mostfilesystem checkers: 

■a Automatically repai r the fi lesystem withoutany questions. (Usethisoption with caution.) Note 

that e2tsck supports -a for backwards com pati bi lity only. Thisoption is mapped to e2fsck's -p 
option, which issafeto use, unlikethe -a option that most fi lesystem checkers support. 

■ r I nteracti vely repai r the fi lesystem (askforconfirmations). Note: It isgenerally a bad ideato use 

thisoption if multipletsck'sarerun in parai lei. Also note that this is e2fsck default behavior; it 
supports thisoption for backwards compatibility reasonsonly. 

AUTHOR 

TheodoreTs'O (tytso@mit.edu) 

Themanual pagewasshamelessly adapted from David Engel and Fred van Kempen'sgeneric fsck front-end program, which 
in turn wasshamelessly adapted from Remy Card's version for theext2 filesystem. 

FILES 

/etc/fstab 

SEE ALSO 

fstab(5), mkfs(8), fsck.minix(8), fsck.ext2<8) Or e2fsck(8), fsck.xiafs(8) 

Version 0.5b, Novemberl994 



fsck.minix 

fsck.minix— A fi I esystem consistency checker for Linux. 
SYNOPSIS 

fsck.minix [ -larvsmf ] device 

DESCRIPTION 

fsck.minix performs a consistency check for the Linux M IN IX filesystem. The current version supports the 14 character and 
30 character fi lename options. 

The program assumes the fi lesystem isquiescent. fsck.minix should not beused on a mounted deviceunlessyou can besure 
nobody iswriting to it (and remember that the kernel can writeto itwhen it searchesforfiles). 

Thedevicewill usually havethefollowingform: 

/dev/hda[1-8] 
/dev/hdb[1-8] 
/dev/sda[1-8] 
/dev/sdb[1-8] 

If the fi lesystem waschanged (that is, repai red), then fsck.minix will print File system nas cnanged and will sync(2) three 
times before exiting. B ecause Linuxdoes not currently haveraw devices, there isno need to reboot at this ti me (versus a 
system that does have raw devices). 

WARNING 

fsck.minix should not beused on a mounted filesystem. U si ng fsck.minix on a mounted filesystem isvery dangerousdueto 
the possi bi lity that deleted fi les are stili in use and can seriously damagea perfectly good filesystem! If you absolutely haveto 
run fsck.minix on a mounted filesystem (that is, the root filesystem), makesurenothing iswriting to the disk and that no 
fi les are "zombies" waiting for deletion. 



ft P d fisoi 



OPTIONS 



-i Listsall filenames. 

■ r P erform s i nteracti ve repai rs. 

-a Performsautomatic repairs(this option implies -r) and servesto answerall of thequestionsasked with the 

default. N otethatthiscan beextremely dangerousin thecaseof extensivefilesystem damage. 
■v Verbose, 
-s 0 utputs super-block information. 

-m ActivatesM IN IX-like "mode not cleared" warnings. 

-t Forcefilesystem check even if thefilesystem was marked asvalid. (Thismarking isdoneby the kernel 

when thefilesystem isunmounted.) 



SEEALSO 

fsck(8), fsck.ext(8), fsck.ext2(8), fsck.xiafs(8), mkfs(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8), reboot(8) 

DIAGNOSTICS 

Therearenumerousdiagnosticmessages.Theonesmentioned herearethemostcommonly seen in normal usage. 
If thedevicedoesnot exist, fsck.minix will print unabie to read super block. If the device exists but is not a M I N IX 

filesystem, fsck.minix will print Bad magic number in super-block. 

EXITCODES 

The exit code returned by fsck.minix isthesum of thefollowing: 



a No errors. 

3 Filesystem errors corrected; system should berebooted if filesystem wasmounted. 

4 Filesystem errors left uncorrected. 
8 Operational errar. 

16 U sage or syntax errar. 



In point of fact, only 0, 3, 4, 7, 8, and 16 can ever be returned. 
AUTHOR 

LinusTorvalds (torvaidsics.heisinki.fi). Errar codevaluesby Rik Faith (faithecs. unc.edu). Added support for filesystem 
valid flag: Dr. Wettstein (greg%wind. uucpgpiains.nodak.edu). Check to preventfsck of mounted filesystem added by Daniel 

Quinlan (quinlaneyggdrasil.com). 

Linux 0.99, 10 January 1994 

ftpd 

ftpd— DARPA Internet FileTransfer Protocol server. 
SYNOPSIS 

ftpd [ - d] [ -1] [-t timeout] [ -T ma x t i meout ] 

DESCRIPTION 

ftpd istheDARPA Internet FileTransfer Protocol server process. The server usestheTCP protocol and listens at the port 
specified in the FTP service specification; seeservices(5). 
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Availableoptions: 

-d Debugging information iswritten to the syslog. 

-ì Each FTP 1 session islogged in the syslog. 

-t T he inacti vi ty timeout period isset to timeout seconds. (The default is 15 minutes.) 

-t A client can also request a different timeout period; the maximum period allowed can beset to timeout 

seconds with the -t option. The default limit is 2 hours. 

The FTP server currently supports the following FTP requests; case isnot disti nguished. 



Request 


D escri pti on 


ABOR 


Abort previous command 


ACCT 


Specify account (ignored) 


ALLO 


Allocate Storage (vacuously) 


APPE 


Append to a file 


CDUP 


C hangeto parent of current working directory 


CWD 


C hanne worki nn di rertorv 

v_< i i u\ i y e vvui i\ 1 1 i y \a\ \ i y 


DELE 


D elete a file 


HELP 


c. ìvp hdn information 

KJ 1 1 1 O VJ \ \ ll\J\ 1 1 IULIUI 1 


LIST 


G i ve list fi les in a directory (' 1 is -ìgA '') 


MKD 


M ake a di rertorv 


MDTM 


Show last modification timeof file 


MODE 


Soerifv data transfer mode 

— ' k-/ V- *w iiy «ULU LI Ul IJI LI 1 1 IUUV_ 


NLST 


G ive name list of fi les i n directory 


NOOP 


D o nothing 


PASS 


Specify password 


PASV 


P repare for server-to- server transfer 


PORT 


Specify data connection port 


PWD 


Print the current working directory 


QUIT 


Termi nate session 


REST 


Restart incomplete transfer 


RETR 


Retri evea file 


RMD 


Remove a directory 


RNFR 


Specify rename-from filename 


RNTO 


Specify rename-to filename 


SITE 


N onstandard commands (see next section) 


SIZE 


Return size of file 


STAT 


Return status of server 


STOR 


Storeafile 


STOU 


Storeafilewith auniquename 


STRU 


Specify data transfer structure 


SYST 


show operati ng system type of server system 


TYPE 


specify data transfer type 


USER 


specify username 


XCUP 


changeto parent of current working directory (deprecated) 
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Request Description 



xcwd change working directory (deprecate*!) 

xmkd makea directory (deprecated) 

xpwd print thecurrent working directory (deprecated) 

xrmd removea directory (deprecated) 

The followi ng non-standard or U N IX-specific commandsaresupported by thesnE request: 



Request Description Example 



umask Change umask site umask 002 

idle Set idletimer site idle 60 

chmod Change mode of a file site chmod 755 

help Givehelp information site help 

The remai ni ng FTP requestsspecified in Internet RFC 959 arerecognized but not implemented. mdtm and size arenot 
specified in RFC 959 but wi II appear in thenext updated FTP RFC. 

The FTP server wi II abort an active fi le transfer onlywhen theABOP, command ispreceded by a Tel net "Interrupt Process" 
(IP) signal and aTelnet "Synch" signal in the command Telnet stream, asdescribed in Internet RFC 959. If asTAT 
command is received during a data transfer, preceded by aTelnet IP and synch, transfer status wi II bereturned. 

ftpd i nterprets fi lenames accordi ngto the giobbi ng conventi onsused by csh(l). Thisallowsusersto utilizethe 
metacharacters Li &*?[]. 

ftpd authenticates users according to four rules: 

Theusernamemustbein the password database and nothaveanull password. In thiscase, apassword mustbeprovided 
by the client before any file operations may be performed. 
Theusernamemust not appear in thefile(seeftpusers(5)). 
Theuser must havea standard shell returned by getusersheii(3). 

If theusernameisanonymousor FTP, an anonymousFTP account must bepresent in the password fi le (user FTP). In 
thiscase, theuser isallowed to log in by specifyi ng any password. (By convention, thisisgiven as the client host's name.) 

In thelast case, ftpd takes special measuresto restrict the ci ient's access pri vi leges. The server performsachroot(2) command 
to the home directory of the FTP user. So that system security isnot breached, it isrecommended that the FTP subtreebe 
constructed with care; the followi ng rules are recommended: 

"ftp M akethehomedirectory owned by rootand unwritableby anyone 

"ftp/bin M akethis directory owned by rootand unwritableby anyone The program is(l) must bepresent to 

support the list command. T hi s program should have mode 111. 

"ftp/etc M akethis directory owned by root and unwritableby anyone The fi lespasswd(5) and group(5) must be 

presentfortheis command to beableto produce owner names rather than numbers. The password field 
in passwd isnot used and should not contai n real encrypted passwords. Thesefiles should bemode444 and 
owned by root. Don't use the system 's/etc/passwd fi le as the password fi le or the system 's /etc/group file 
asthegroupfilein the~ftp/etc directory. 

Pa "ftp/pub M akethis directory mode 755 and owned by root. Create a subdirectory in "ftp/pub with the appropriate 
mode (777 or 733) if you wantto allow normal users to upload file. 

SEEALSO 

ftp(l), getusershell(3), ftpusers(5), syslogd(8) 

BUGS 



T he anonymous account isinherently dangerousand should avoided when possi ble. 
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T he server must run as the super-user to create socketswith privileged portnumbers. It maintainsan effectiveuser ID ofthe 
logged-in user, reverting to the super-user only when binding addressesto sockets. T he possible security holes have been 
extensively scrutinized but are possi bly incomplete 

HI STORY 

Thecommand appeared in BSD 4.2. 

BSD 4.2, 16 M arch 1991 



ifconfig 



ifconfig— Configureanetworkinterface. 
SYNOPSIS 



ifconfig [interface] 

ifconfig interface [aftype] options 



address 



DESCRIVO N 

ifconfig isused to set up (and maintain thereafter) the kernel-resi dent network interfaces. It isused at boottimeto configure 
most of them to a running state. After that, it is usuai ly only needed when debugging or when system tuning isneeded. 

If no argumentsaregiven, ifconfig just displ ays the status of the currently defi ned interfaces. If the single interface argument 
isgiven, it displays the status ofthe given interface only. Otherwise, itassumesthatthings haveto besetup. 

ADDRESS FAMILIES 

If the first argument after the interface nameisrecognized asthenameof asupported address fami ly, that address fami ly is 
used fordecodingand displayingall protocol addresses. Currently supported address families include inet (TCP/IP, default) 
and ax25 (AM PR Packet Radio.) 



OPTIONS 

interface 
up 

down 

[-]arp 

[ - ]trailers 

[-Jallmulti 

metric N 

mtu N 

dstaddr addr 



Thenameof theN ET interface. T hi susually isa namesuch aswd0, si3, or something li ke that: 
adevicedriver namefollowed by aunit number. 

Thisflag causesthe interface to beactivated. It i s i m plicitly speci fi ed if the interface isgiven a 
new address (seebelow). 

T hisflagcauses the dri ver forthis interface to beshut down and isuseful when things start 
goingwrong. 

Enable or disablethe use of theARP protocol on this interface. If theminus(-) sign ispresent, 
theflagisturnedOFF. 

E nable or di sable the use of trai lers on Ethernet frames. This is not used i n the current 
implementation of N ET. 

Enableor disablethe promiscuous modeof the interface. Thismeans that ali incomingframes 
get sent to the network layer ofthe system kernel, allowingfor networking monitoring. 
Thisparameter sets the interface metric. It is not used at present, but weimplement it for the 
future 

Thisparameter sets the M aximum Transfer U nit (MTU) of an interface For Ethernet, this isa 
number in the rangeof 1000-2000 (default is 1500). For SLIP, use something between 200 and 
4096. N ote that the current implementation does not handlelP fragmentation yet, so you'd 
better maketheMTU largeenough! 

Set the"other end's" IP address in caseof apoint-to-point link, such asPPP. This keyword is 
obsoleted by the new pointopoint keyword. 



inetd 
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netmask addr 



[-[broadcast [addr] 



- Ipointopoint [addr] 



hw 



address 



Set the IP network mask forthis interface. Thisvaluedefaultsto the usuai class A, B, orC 
network mask (as deducted from the interface IP address), butitcan be setto any valueforthe 
useof subnetting. 

If the address argument isalso given, set the protocol broadcast address forthis interface. 
Otherwise, it only sets the iff_broadcast flag of the interface If the keyword was preceded by a 
minus(-) sign, then theflag iscleared instead. 

This keyword enablesthepoint-to-point modeof an interface, meaning that it is a direct link 
between two machineswith nobody else listening on it. (At least we hope that this isthe case, 
grin :-).) 

If the address argument isalso given, set the protocol address of the other sideof the link, just 
li ke the obsolete dstaddr keyword does. Otherwise, it only sets the iff_pointopoint flag ofthe 
interface. If the keyword was preceded by aminus(-) sign, then theflag iscleared instead. 
Set the hardware address of this interface if the device driver supports this operation. T he 
keyword must befollowed by the name ofthe hardware class and the printable ASC 1 1 
equivalent of the hardware address. H ardware classes currently supported include ether 
(Ethernet), ax25 (AM PR AX.25), and ppp, although the latter is not really supported yet. 
ThehostnameorIP address(a hostnamewill beresolved into an IP address) of that interface. 
This parameter is required, although thesyntax doesn't currently requireit. 



FILES 

/dev/net/socket 

BUGS 

None so far, although thesyntaxcheckingcould be better. 
AUTHOR 

Fred N . van Kempen (waltj Kuwait. nl.mugnet.org) 



6 October 1993 



inetd 

inetd— I nternet superserver. 
SYNOPSIS 

inetd [ -d] [confi gurati ori file] 

D ESC RIPTIO N 

inetd should be run at boottimeby /etc/ re. locai (seerc(8)). It then listens for connections on certain I nternet sockets. 
When a connection isfound on oneof its sockets, it decides what servicethesocket correspondsto and invokes a program to 
servi ce the requ est. After the program isfinished, it conti nuesto li sten on thesocket (except in somecases, which are 
described later). Essentially, inetd allowsrunning onedaemon to i nvoke several others, reducing load on the system. 

Theoption available for inetd: 

-d Turnson debugging. 

Upon execution, inetd reads its confi gurati on informati on from a configurati on file, which, by default, is/etc/inetd.cont. 
Theremust bean entry for each field ofthe configurati on file, with entries for each field separated by atab or a space. 
Commentsaredenoted by a # at the beginningof a line. Theremust bean entry for each field. The fields ofthe configura- 
ti on fileareasfollows: 
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service name 
socket type 
protocol 

wait /nowait [ . max ] 

user[ .group] 

server program 

server program arguments 

To speci fy an Sun-RPC based service, theentry would contain thesefields: 

service name/version 

socket type 

rpc/protocol 

wait /nowait [ . max ] 

user[ .group] 

server program 

server program arguments 

T he service-name entry is the name of a valid service in the fi le /etc/services . For internai services, the service name must 
be the offici al nameof the service (that is, the first entry in /etc/services). When used to specify a Sun-RPC based service, 
thisfield isa valid RPC service name in thefile /etc/rpc. The part on theright of the / istheRPC version number. Thiscan 
simply beasinglenumeric argument or a rangeof versions. A rangeisbounded by thelow version to the high version 

- rusers/1 -3. 

The socket type should beone of stream, dgram, raw, rdm, or seqpacket, dependi ng on whether the socket isastream, 
datagram, raw, reliably delivered message, or sequenced packet socket. 

The protocol must bea valid protocol asgiven in /etc/protocois. Examplesmight betcpor udp. Rpc-based servi cesare 
speci fi ed with the rpc/tcp or rpc/udp servicetype. 

Thewaitynowait entry isappli cable to datagram socketsonly. (Other sockets should have a nowait entry in this space) If a 
datagram server connectsto its peer, freeing the socket so inetd can receivefurther messageson the socket, it issaid to bea 
multithreaded server and should use the nowait entry. For datagram serversthat processali incomingdatagramson a socket 
and eventually timeout, the server issaid to besingle-threaded and should use a wait entry. comsat(8), biff(l), and taikd(8) 
are examples of the I after type of datagram server. Tftpd(8) is an exception; it is a datagram server that establishes pseudo- 
connections. 

It must belisted aswait in order to avoid a race the server reads the first packet, createsa new socket, and then forksand 
exitsto allow inetd to check for new service requeststo spawn new servers. The optional max suffix (separateci from wait or 
nowait by a dot) specifies the maximum number of server instances that may bespawned from inetd within an interval of 60 
seconds. W hen omitted, max defaults to 40. 

The user entry should contain the usernameof the user aswhom theserver should run. This allows for servers to begiven 
less permi ssion than root. An optional group name can bespecified by appendi ng a dotto theusernamefollowed by the 
group name. This allows for servers to run with a different (primary) group ID than specified in the password file If a group 
isspecified and the user is not root, thesupplementary groupsassociated with that user wi II stili beset. 

The server-program entry should contain the pathnameof the program that isto beexecuted by inetd when a request is 
found on its socket. If inetd provi des th i s servi ce i ntern al I y, this entry should be internai. 

Theserver program arguments should appear just as arguments normally do, starti ng with argv[0], which isthe nameof the 
program. If the service isprovided internai ly, the word internai should take the place of this entry. 

inetd provides several trivi al services i ntern al ly by useof routines within itself. These services are echo, discard, cnargen 
(character generator), daytime (human readabletime), and time (machinereadabletimein theform of the number of seconds 
si nce midnight, January 1, 1900). Ali of these services areTCP based. For detailsof these services, consult the appropriate 
RFC from the Network Information Center. 
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inetd rereads itsconfiguration filewhen it receivesa hangup signal, sighup. Services may beadded, deleted, or modified 
when theconfiguration fileisreread. inetd createsafile /etc/inetd.pi d that contains itsprocess identifier. 

SEEALSO 

comsat(8), f ingerd(8), ftpd(8), rexecd(8), rlogind(8), rshd(8), telnetd(8), tftpd(8) 

HI STORY 

Thecommand appeared in BSD 4.3. Support for Sun-RPC based servicesis modeled after that provided by Sun-OS 4.1. 

BSD 4.3, 16 March 1991 



init, telinit 

init, teiinit— Process control initialization. 
SYNOPSIS 

/sbin/init [ -t sec ] [0123456SsQq ] 
/sbin/telinit [ -t sec ] [0123456sSQqabc ] 

DESCRIPTION 

init 

init isthefather of ali processes. Its primary roleisto create processesfrom a script stored in thefile/etc/inittab (see 
inittab(5)). T his fi le usuai ly hasentries that cause init to spawn gettys on each line that userscan log in. It also controis 
autonomous processes requi red by any parti cular system. 

A run leve! is a software configurati on of the system that allowsonly a selected group of processes to exist. The processes 
spawned by init for each of theserun leve! s are defi ned in the/etc/inittab file, init can bein oneof eight run levels, 06 and 
s or s. The run leve! ischanged by havinga privi leged user run /sbin/ teiinit, which sends appropri atesignalsto init, telling 
itwhich run leve! to changeto. 

After init isinvoked asthelast step of the kernel booti ng, it looksforthefile /etc/inittab to seeif thereisan entry of the 
typeinitdefauit (see inittab(5)). initdetauit determi nes the initial run leve! of the system. If thereisno such entry or no 
/etc/inittab at ali, a run leve! must beentered at the system console. 

Run level sor s bri ngs the system to single-user mode and does not requi re an /etc/initttab file. In single-user mode, 

/bin/sh isinvoked On /dev/console. 

/dev/consoie need not necessari ly bethephysical system console. W hen init istold to enter single-user mode or run level 1 
(either directly, by init s, or by telling shutdown to enter mai ntenance mode), it will link the terminal li ne thecommand 
wasexecuted from to /dev/consoie. Thedevice /dev/systty iscalled the physi cai system consoleandthedevice/dev/consoie 
iscalled the logicai system console. If thelogical system console is not the physi cai system console, pressing the combination 
Ctrl+Alt-tO e! on the physi cai system console will forcea relink of /dev/consoie to /dev/systty. A terminal linecan only 
become the logicai console if it's I isted in the fi le /etc/securetty. Ali thisisin preparati on of the day that the Linux kernel 
will support serial console. 

Beware: If you want to run x or anything else that isawareof Virtual Consoles, thelogical system console (/dev/consoie) 
needsto bethesameasthephysical system console (/dev/systty). 

When entering single-user mode init readstheconsole'Siocti(2) statesfrom /etc/iocti.save. If thisfiledoesnot exist, init 
i n i ti al i zes the I i ne at 9600 baud and with clocal setti ngs. When init leaves single-user mode, it storestheconsole'siocti 
setti ngs in thi s fi le so it can re-use them forthenext single-user session. If thelogical system console ischanged to another 
terminal line, the setti ngs of the li ne from which themit or teiinit command wasgiven are stored in /etc/iocti.save too, 
so that the terminal linewill beinitialized correctly in single-user mode. 



Part V 1 1 1 : Admi ni strati on and P ri vi I eged Commands 



When entering a multi-user mode the first ti me, inìt performstheboot and bootwait entri esto allow filesystemsto be 
mounted beforeuserscan log in. T hen ali entriesmatchingtherun level areprocessed. 

Each timeachild terminates, init recordsthefact and thereason it died in /etc/utmp and /var/adm/wtmp if these fi les exist. 

After it has spawned ali theprocesses speci fi ed, init waitsfor oneof its descendant processesto die, a powerfail signal, or a 
signal by /sbin/teumt to change the system 'srun level. W hen oneof these three condì tionsoccurs, it re-examinesthe 
/etc/inittab file N ew entri escan beadded to thisfileat any ti me. H owever, init stili waitsfor oneof the three conditions 
to occur. To providefor an instantaneousresponse, the q or q command can wakeup init to re-examinethe /etc/inittab 
file. 

If init isnot in single-user mode and receives a powerfail signal, special powerfail entriesareinvoked. 

When init isrequested to change the run level, it sendsthewarning signal sigterm to ali processes that areundefined in the 
new run level. Itthen waits20 secondsbeforeforcibly terminati ng these processes viathekill signal sigkill. 

N otethat init assumesthat ali these processes (and their descendants) rem ai n in thesameprocessgroup that init origi nally 
created forthem. If any processchangesitsprocessgroup affiliation, itwill not reca ve these signals. Such processes need to 
beterminated separately. 

telinit 

/sbin/teiinit islinked to /sbin/init. It takesa one-character argument and signals init to perform the appropriate action. 
Thefollowing arguments serve as di recti vesto /sbin/teiinit: 

a, 1, 2, 3, 4, 5, or 6 Teli /sbin/init to switch to thespecified run level. 

a, b, c Teli /sbin/init to process only those /etc/inittab fi le entri es having run level a, t>, ore. 

q or q Teli /sbin/init to re-examinethe /etc/inittab file, 

s or s Teli /sbin/init to switch to single-user mode. 

/sbin/teiinit can also teli init how much timeit should wait between sending processes the term and theKiLL signal; the 
default i s 20 seconds, but it can bechanged by the -t sec option. 

/sbin/teiinit can beinvoked only by userswith appropriate pri vi leges. 
RUN LEVELS 

Run levelse, 1, and 6 arereserved. Run level 0 isused to halt the system, run level 6 isused to reboot the system, and run 
level 1 isused to getthesystem down into single-user mode. Run level s isnot really meantto beused directly but should be 
used by seri pts that areexecuted when entering run level 1. For moreinformation on this, seetheman pagesfor snutdown(l) 

and inittab(5). 

FI LES 

/etc/inittab 

/dev/console 

/dev/systty 

/etc/ioctl.save 

/etc/utmp 

/var/adm/wtmp 

CONFO RMINGTO 

init iscompatiblewith theSystem V init. The seri pts that are used with it, however, are mostly modeled after the BSD 
startup seri pts. Th ere are startup seri pts available that let Linux boot more like a System V system, but most peoplefind 
them too complex. 

WARNINGS 

init assumesthat processes and descendants of processes remai n in thesameprocessgroup that was origi nally created for 
them. If the processes change their group, init can't kill them and you might end up with two processes readingfrom one 
terminal line. 
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DIAGNOSTICS 

If /sbin/init findsthat it is conti nuously respawning an entry morethan ten timesin two minutes, it will assume thatthere 
isan errar in thecommand string, generate an errar messageon the system console, and refuse to respawn this entry until 
either five minutes has elapsed or it receives a signal. This prevents it from eating up system resources when someone makes a 
typographical errar in the/etc/inittab fi le or the program for the entry isremoved. 

AUTHOR 

M iquel van Smoorenburg (miqueisedrinkei.ni.mugnet.org); ini ti al manual pageby M ichael H aardt 

(u31 b3hs@pool . inf ormatik. rwth -aachen.de). 

SEEALSO 

getty(l), login(l), sh(l), who(l), shutdown(l), kill(2), inittab(5), utmp(5) 

19 January 1994 
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innd, inndstart— InterN etN ewsdaemon. 
SYNOPSIS 

innd [ -a ][-c days ][-d ] [ -f ][-i count ][-o count ][-l size ] 

[-m mode ][-n flag ] [ -p port ][-r ][-s ][-S host ][-t timeout ][-u ][-x ] 

inndstart [ f I ags ] 

DESCRIVO N 

innd, the InterN etN ewsdaemon, handles ali incomi ng N NTP feeds. It readstheactive(5), newsfeeds(5), and hosts.nntp(5) 
filesinto memory. Itthen openstheN NTP portto recévearticlesfrom remote sites, aU N IX-domain stream socketto 
receivearticlesfrom locai processes such asnnrpd(8) and rnews(l), and aU N IX-domain datagram socket for useby 
ctiinnd(8) to di rect the server to perforai certain actions. It also opensthetustory(5) database and two log fi lesto replace its 
standard output and standard errar. If the -p flag isused, then the N NTP port isassumed to beopen on thespecified 
descriptor. (If thisflag isused, then innd assumesit isrunningwith theproper permissionsand it doesnot cali chown(2) on 
any filesor directories it creates.) 

Once the files and sockets have been opened, innd waitsfor connectionsand datato be ready on itsportsby usingseiect(2) 
and non-blocking I/O. If no data isavailable, then it flushes its in-core data structures. The default number of secondsto 
timeout beforeflushing is 300. This timeout may bechanged by usi ng the-t flag. 

To li mit the number of incomi ng N NTP connections, use the -i flag. A valueof 0 suppresses this check. 

To li mit the number of files that are kept open foroutgoingfilefeeds, use the -0 flag. The default is the number of available 
descriptorsminussomereserved for internai use. 

To li mit the size ofan article, use the -1 flag. If thisflag isused, then any article bigger than size bytesisrejected. The 
default isno checking, which can also beobtained by usi ng a valueof 0. 

innd rejects articles that are too old. Although this behavior can be controlied by the history database, occasi onally a site 
dumpsa batch of very old news back onto the network. Use the -c flag to specify a cutoff. For example, -c2i rejects any 
articles that were posted morethan 21 days ago. A valueof 0 suppresses this check. 

innd usually putsitself into the background, sets its standard output and errar to log files, and disassociates itself from the 
terminal. Usi ng the -d flag instructs the server to notdo this, whereas usi ng the-t flag just leaves the server runningthe 
foreground. T he logs are usually buffered; usethe-u flagto havethem unbuffered. 

To start the server in a paused orthrottled state (see ctiinnd(8)) use the -m flag to set the initial running mode The 
argument should start with a single letter g, p, or t to emulate the go, pause, or throttie commands. 
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If the-r flag isused, the server renumberstheactivefileas if a renumber command weresent. 

If the-s flag isused, then innd does not do any work but instead just checksthesyntaxof thenews-feedsfile. It exitswith an 
error status if there are any errarsi the actual errors are reported in sysiog(3). 

If innd getsan NOSPC error (seeintro(2)) whiletrying to write the acti ve file, an articlefile, or the history database, it sends 
itself a throttie command. T his also happensif it getstoo many I/O errors whi le writingto anyfiles. 

Any subprocesses spawned by the server get a nice(2) value of 10. 

The-n flag specifies whether pausi ng or th rotti ing the server should also di sabl e future news- reading processes. A value of y 
m akes n ews readers act as th e server, avalueofnallowsnews read i n g even w h en th e server isnotrunning. 

If the-s flag isused, then innd runsin slave mode. When runningasaslave, the server only acceptsarticlesfrom the 
specified host, which must use the xrepiic protocol extension. N otethat either the host must appear in thenosts.nntp fi le or 
the server must bestarted with the-a flag. 

By default, if a host is not menti oned in thenosts.nntp file, then the connection ishanded off to nnrpd. If the-a flag isused, 
then any host can connect and transfer arti ci es. 

If the -x flag isused, then aXref header isadded to ali articleseven if they are not cross-posted. 

inndstart is a small front-end program thatopenstheNNTP port, sets its user I D andgrouplD to the news mai ntainer, 
and then executes innd with the -p flag and a minimal secureenvironment. T his is a small, easily understood front-end 
program that can beused if a site does not want to run innd with root privileges. 

CONTROL MESSAGES 

Arri vi ng arti ci es that have a Control header or havea Subject header that starts with thefivecharacterscmsg arecalled control 
messages. Except forthecancel message, thesemessagesareimplemented by external programsin the/news/bin/controi 
directory. (Cancel messages update the history database, so they must behandled internally; thecost of synching, locking, 
and then unlocking istoo high, given thenumber of cancel messages that are received.) 

When acontrol message arri ves, the first word of thetext isconverted to lowercaseand used as the nameof the program to 
execute; if thenamed program does notexist, then a program named defauit isexecuted. 

Ali control programsareinvoked with four parameters. The first istheaddressof theperson who posted the message; thisis 
taken from theSender header. If that header isempty, then it istaken from theFrom header. The second parameter isthe 
addressto send repliesto; this istaken from theReply-To header. If that header isempty, then the poster's address isused. 
Thethird parameter is a name under which the arti eie i s fi led, relati veto the news spool directory. The fourth parameter is 
the host that sent the article, as specified on thePath line. 

Thedistribution of control messageisalso different from thoseof standard articles. 

Control messages are usuai ly fi led in the newsgroup named control. They can befiled in subgroups, however, based on the 
control message command. For example, anewgroup message is fi led in control, newgroup if that group exists, otherwise it wi II 
befiled in control. 

Sitesmay explicitly have the "control" newsgroup in their subscription list, although it isusually bestto excludeit. If a 
control message is posted to a group whose name ends with the four characters .cti, then thesuffix is stri pped off and what 
isleft isused as the group name. For example, a cancel message posted to news.admin.cti will besentto ali sitesthat 
subscribeto control or news.admin. newgroup and rmgroup messages receive additional special treatment. If the message is 
approved and posted to the nameof the group bei ng created or removed, then the message is sent to ali sites whose 
subscription pattemswould cause them to receive articles posted in that group. 

If an article is posted to a newsgroup that starts with thethreelettersto., it gets special treatment if the newsgroup does not 
exist in the acti ve fi le. The article is fi led into the newsgroup to and it issent to the first site named after the prefix. For 
example, a posti ng to to.uunet isfiled in to and sent to the site uunet. 



PROTOCOL DIFFERENCES 

innd implementstheN NTP commandsdefined in RFC 977 with thefollowing differences: 
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■ The list may befollowed by an optional active, active. times, or newsgroups argument. This common extension isnot 
fui ly supported; see nnrpd(8). 

■ Theauthinfo user and authinto pass commands are implemented. T hese are based on the reference U N IX implemen- 
tation; no other documentation isavailable 

■ A new command, mode reader, isprovided. Thiscommand causes the server to pass the connection on to nnrpd. The 
command mode query isintended for future use and iscurrently treated thesameway. 

■ A new command, xrepiic news, group : arti, news, group: art], isprovided. T his is simi lar to theihave command (the 
same reply codes are used) except for the data that follows the command word. The data consists of entri es separated by 
a single comma. Each entry consists of a newsgroup name, a colon, and an articlenumber. 0 nce processed, thearticleis 
filed in the newsgroup and article numbers specified in thecommand. 

■ A new command, xpatn messageid, isprovided. Theserver respondswith a 223 responseand a space- separated listof 
fi lenames where the arti eie was fi led. 

■ The only other commands implemented aretiead, heip, inave, quit, and stat. 

HEADER MODIFICATIONS 

innd modifiesasfew article headersas possi ble, although it could be better in this area. 
Thefollowing headers, if present, areremoved: 

Date-Received 

Posted 

Posti ng-V ersion 
Received 
Relay-V ersion 

E mpty headers and headers that consist of nothi ng but whi tespace are also dropped. 
The locai site's name and an exclamation point areprepended to thePath header. 
TheXref headerisremoved. If thearticleiscross-posted, anew header is generateci. 
TheLines header isadded if itismissing. 

innd doesnot rewriteincorrect headers. For example, it doesnot replace an incorrect Lines header but rejects the article. 
LOGGING 

innd reportsall incomi ng articles in its log file. Thisisatext filewith a variablenumber of space-separated fieldsin oneof the 
followingformats: 

mon dd hh:mm:ss.mmm + feed <Message-ID>site. . . 
mon dd hh:mm: ss. mmm j feed <Message-ID> site... 
mon dd hh:mm: ss. mmm c feed <Message-ID> site... 
mon dd hh:mm:ss.mmm - feed <Message - ID> reason... 

The first threefields are the date and timeto millisecond resolution. The fifth fidd is the site that sent the article (based on 
thePath header), and thesixth field isthearticle's M essage-l D ; they will contai n aquestion mark if theinformation isnot 
available. 

Thefourth field indicateswhether the article was accepted. If it isa plussign, the article was accepted. If it istheletter j, the 
articlewasaccepted, but ali of newsgroups havea j in their active field, so the arti ci e was fi led into the "junk" newsgroup. If 
thefourth field istheletter c, a canee! message was accepted befo re the ori gin al article arri ved. In ali threecases, the article 
hasbeen accepted and the site. . . field contai ns the spaceseparated list of sitesto which thearticleis sent. 

If thefourth field isa minussign, the article was rejected. The reasons for rejection include 
%s header too long 
%s wantsto cancel <ts>by %s 
Article exceedslocal limitof %s bytes 
Article posted in thefuture— %s 
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Bad %s header 
Can't write hi story 
Duplicate 
Duplicate %s header 
EOF in headers 
Linecount%s !=%s +■ %s 
M issing%s header 
N o body 

N o colon- space in %s header 
N o space 

Space before colon in %s header 

Too old— %s 

U napproved for%s 

U nwanted newsgroup %s 

Unwanted distri bution %s 

W hitespace in "N ewsgroups" header— %s 

Where%s, above, isreplaced by more specific informati on. 

N otethat if an articleisaccepted and noneof the newsgroups are vali d, it islogged with both two lines, a j li ne and a minus 
sign line. 

innd also makes extensi ve reports through sysiog. The first word of the log messageisthenameof the site if the entry issite- 
specific (such asaconnected message). T he fi rst word is me if the message rei atesto the server itself, such aswhen a read errar 
occurs. 

If thesecond word isthefour letterscant, an errar is bei ng reported. In thiscase, thenext two wordsgenerally namethe 
system cali or library routinethat failed and theobject upon which the action was performed. Therest of the line might 
contain other information. 

In other cases, thesecond word attemptsto summarizewhat changehas been made, and therest of the line gives more 
specific information. Theword internai generally indicatesan internai logie errar. 

HI STORY 

W ritten by Rich $alz (rsaiz@uunet. uu.net) for InterN etN ews. 
SEE ALSO 

active(5), ctlinnd(8), dbz(3z), history(5), hosts.nntp(5), inn.conf(5), newsf eeds(5), nnrpd(8), rnews(l), syslog(8) 

innxmit 

innxmit— Send U senet articlesto a remoteN NTP server. 
SYNOPSIS 

innxmit [ -A altspool ][-a ][-d ][-M ][-r ][-t timeout ] 
[-T timeout ][-p ][-S ] host file 

D ESC RIFTIO N 

innxmit conneetsto the N NTP server atthespecified host and sendsitthearticlesspecified in thebatchfilenamed file. It is 
usually invoked by a script run out of cron(8) that usessniock(l) to lock thehostname, followed by actiinnd(8) command to 
flush thebatchfile. 



innxmit usually blocks unti I the connection ismade. To specify a timeout on how longto try to make the connection, use the 
-t flag. To specify the total amount of timethat should beallowed for article transfers, use the -t f lag. The default isto wait 
until an I/O errar occurs or ali thearticles havebeen transferred. If the -t flag isused, thetime ischecked just beforean 
article isstarted; it doesnot abort a transfer that isin progress. Both valuesaremeasured in seconds. 

If the file isnot an absolute pathname, it istaken relative to the/news/spooi/out.going directory. It is usually written by 
specifyingthewnm flagsin thenewsfeeds(5) file. Each line in the batchfi le should bein oneof thefollowing formats: 

fi I e n a me Me s s a g e - 1 D 
fi I e n a me 

The menarne field names the article to besent. If it isnot an absolute pathname, it istaken relative to the news spool 
directory, /news/spooi. If theMessage-iD field isnot specified, itisobtained by scanning the article Thefiiename and 
Message-id fields are separated by a space. 

If acommunication errorsuch asawnte(2) fai Iure occurs, innxmit stopssendingand rewrites the batchfi le to contain the 
current article and any other unsent articles. 

If the remote server sendsan unexpected reply code, innxmit requeues the article and proceeds. U se the -r flag if the article 
should not be requeued. 

U pon exit, innxmit reports transfer and C PU usagestatisticsvia sysiog(3). If the -v flag isused, they arealso printed on the 
standard output. If ali articles weresent successfully, innxmit removesthebatchfile; otherwise, it rewrites it to contain the list 
of unsent articles. If no articles weresent or rejected, the fi le is left untouched. Thiscan cause the batchfi le to grow 
excessi vely largeif many articles havebeen expired and there are com munì cation problems. To always rewrite the batchfi le, 
use the -a flag. I f the -p flag isgiven, then no connection ismade and the batchfi le ispurged of entri es that referto filesthat 
no longer exist. Thisimpliesthe -a flag. 

If the-s flag isgiven, then innxmit offers arti desto the specified hostusingthexrepiic protocol extension described in 
innd(8). To usethisflag, the input fi le must contain the history data (commas are trans! iterated to spaces by the server). For 
thisflagto beused, the input must contain thenecessary history entri es. Thisis usually doneby setti ng up awnR entry in the 
newsfeeds file 

Use the -d flag to print debugging informati on on standard error. Thisshows the protocol transactionsbetween innxmit and 
the N N T P server on the remote host. 

If the-M flag isused, innxmit scansan article's headers before sendi ng it. If the article appearsto bea M IM E arti de that isnot 
in seven-bit format, thearticle issent in "quoted-printable" form. 

The -a flag may beused to specify an alternate spool directory to use if the article isnot found; thisis usually an N FS- 
mounted spool directory of a master server with longer expirati on times. 

HISTORY 

W ritten by Rich $alz (rsaizguunet.uu.net) for InterN etN ews. 
SEEALSO 

ctlinnd(8), innd(8), newsf eeds(5), shlock(l) 

ipcrm 

ipc rm— R em o ve i pc f aci I i ti es. 
SYNOPSIS 

ipcrm [ shm ] msg j sem ] i d 



DESCRIPTION 

ipcrm removestheresource specified by i d 
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SEEALSO 

ipcs(8) 

AUTHOR 

Krishna Balasubramanian (baiasub@cis.ohio-state.edu) 

Linux 0.99, 9 October 1993 



ipcs 

ipcs— Provide information on ipc faciliti es. 
SYNOPSIS 

ipcs [ -asmq ] [ -tclup ] 
ipcs [ -smq ] -i i d 
ipcs -h 

D ESC RIPTIO N 

ipcs provides information on the ipc faci litiesfor which the calli ng process hasread access. 
The -i option allowsaspecific resourcei d to bespecified. Only information on thisi d isprinted. 
Resources may bespecified asfollows: 



-m Shared memory segments 

-q M essagequeues 

-s Semaphorearrays 

-a Ali (thisis the default) 

T h e output f o rm at m ay be speci f i ed as f o 1 1 ows: 

-t Time 

-p PID 

-c Creator 

-ì Limits 

-u Summary 

SEEALSO 

ipcrm(8) 

AUTHOR 



Krishna Balasubramanian (baiasub@cis.ohio-state.edu) 

Linux 0.99, 9 October 1993 

kbdrate 

kbdrate— Reset the keyboard repeat rate and delay ti me. 
SYNOPSIS 

kbdrate [ -s ] [ - r rate ] [ - d delay ] 




DESCRIPTIO N 

kbdrate isused to changethelBM keyboard repeat rate and delay ti me Thedelay istheamount of timethat a key must be 
pressed before it starts to repeat. Using kbdrate without any optionsresets the rate to 10.9 characters per second (cps) and 
thedelay to 250 milliseconds(ms).ThesearethelBM defaults 

0PTI0NS 

-s Silent. N o messagesareprinted. 

-r rate C hangethe keyboard repeat rate to rate cps. Theallowablerangeisfrom 2.0 to 30.0 cps. Only certain 

specific values are possible, and the program selectsthenearest possiblevalueto theonespecified. The 
possi blevalues are given, in characters per second, asfollows: 2.0, 2.1, 2.3, 2.5, 2.7, 3.0, 3.3, 3.7, 4.0, 4.3, 

4.6, 5.0, 5.5, 6.0, 6.7, 7.5, 8.0, 8.6, 9.2, 10.0, 10.9, 12.0, 13.3, 15.0, 16.0, 17.1, 18.5, 20.0, 21 .8, 24.0, 
26.7, 30.0. 

-d delay C hange the delay to dei a y milliseconds. Theallowablerangeisfrom 250 to 1000 ms, buttheonly possible 

values (based on hardware restri ctions) are 250 ms, 500 ms, 750 ms, and 1000 ms. 

BUGS 

N ot ali keyboards support ali rates. 

Notali keyboards have the rates mapped in thesameway. 

Setti ng the repeat rateon the Gateway A nyKey keyboard does notwork. If someonewith a Gateway fi guresout how to 
program the keyboard, pleasesend mail to faitn@cs. unc.edu. 

FILES 

/etc/rc. locai 
/dev/port 

AUTH0R 

Rik Faith (faithgcs.unc.edu) 

Linux 1.1.19, 22 Junel994 

klogd 

kiogd— Kernel logdaemon. 
SYN0PSIS 

klogd -c [n ] -d -f [f nane ] -os 

DESCRIPTIO N 

kiogd isa system daemon that interceptsand logs Linux kernel messages. 
0PTI0NS 



-c Sets the default log leve! of console messages to [nj. 

-d E nables debugging mode Thiswill generate a lot of output to stderr. 

-t Logs messages to thespecified filename rather than to thesysiog facility. 

-0 Executein one-shot mode. Thiscauses kiogd to read and log ali the messages that arefound in the kernel 

message buffers. After a single read and log cycle, the daemon exits 
-s Force kiogd to usethesystem cali interface to the kernel message buffers. 
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OVERVIEW 

Thefunctionality of kiogd hasbeen typically incorporateci into other versi onsof sysiogd, but thisseemsto bea poor place 
forit. In the modem Linux kernel, anumberof kernel messaging issuessuch assourcingand prioritization mustbe 
addressed. Incorporati ng kernel logging into a separate process appears to offer a cleaner separati on of services. 

In Linux, therearetwo potential sourcesof kernel log information: the /proc filesystem and thesyscaii (sys_sysiog) 
interface, although ulti mately they areoneand thesame kiogd isdesigned to choosewhichever sourceof information isthe 
most appropriate. It doesthis by first checkingfor thepresenceof a mounted /proc filesystem. If thisisfound, the 
/proc/kmsg fileisused as the source of kernel log information. If the proc filesystem is not mounted, kiogd uses a system cali 
to obtain kernel messages. Thecommand-lineswitch (-s) can beused to force kiogd to usethesystem cali interface asits 
messaging source. 

If kernel messages are di rected through the sysiogd daemon, the kiogd daemon, asof version 1.1, hastheability to properly 
prioritize kernel messages. Prioritization of the kernel messages wasadded at approximately the pn3 level of the kernel. The 
raw kernel messages are of the form: 

<[0-7]>Somet hi ng said by the kernel. 

T he priority of the kernel messageisencoded as a single numeric digit enclosed inside the<> pair. Thedefinitionsof these 
values isgiven in the kernel include file kemei.h. W hen a messageis received from the kernel, the kiogd daemon readsthis 
priority level and assi gns the appropriate priority level to thesysiog message. If file output (-f) isused, the prioritization 
sequence is left prepended to the kernel message. 

The kiogd daemon also allows the abi lity to alter the presentati on of kernel messages to the system console. Consequent with 
the prioritization of kernel messages was the inclusi on of default messaging levels for the kernel. In a stock kernel, the default 
console log level is setto 7. Any messages with a priority level numerically lowerthan 7 (higher priority) appear on the 
console. 

M essagesof priority level 7 areconsidered to be debug messages and do not appear on the console. M any admi nistrators, 
parti cularly in a multi- user environment, prefer that ali kernel messages be h and I ed by kiogd and either di rected to a file or 
to the sysiogd daemon. Thispreventsnuisance messages such asiine printer out of paper or disk changedetected from 
clutt ering the console 

By default, the kiogd daemon executes a system cali to inhibit ali kernel messages (except for panics) from bei ng displayed on 
the console. The -c switch can be used to alter thisbehavior. Theargument given to the-c switch speci fi es the priority level 
of messages that are di rected to the console. N otethat messages of a priority value lowerthan the indi cated number are 
di rected to the console. 

Forexample, to have the kernel display ali messages with a priority level of 3 (kern err) or more severe, thefollowing 
command isexecuted: 
kiogd -c 4 

Thedefinitionsof thenumeric values for kernel messages are given in thefile kernel. h, which can befound in the 
/usr/inciude/iinux directory if the kernel sources are installed. These values parallel thesysiog priority values, which are 
defined in thefile sysiog.n, found in the /usr/inciude/sys subdirectory. 

The kiogd daemon can also beused in aone-shot mode for reading the kernel message buffers. One-shot modeisselected by 
speci fying the -0 switch on the command line. Output isdi rected to either the sysiogd daemon orto an alternate file 
specified by the -f switch. 

For example, to read ali the kernel messages after a system boot and record them in afilecalled kmi.msg, thefollowing 
command isgiven: 

kiogd -0 -f ./krnl.msg 

SIGNAL HANDLING 

The kiogd daemon respondsto six signals: sighup, sigint, sigkill, sigterm, sigtstp, and sigcont. ThesiGiNT, sigkill, 
sigterm, and sighup signals cause the daemon to closeits kernel log sources and termi nate gracefully. 
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T he sigtstp and sigcont signalsareused to start and stop kernel logging. U pon receipt of asiGTSTP signal, thedaemon closes 
its log sourcesand spinsin an idle loop. Subsequent receipt of a sigcont signal causes thedaemon to go through its 
initialization sequenceand rechoosean input source. Using sigstop and sigcont in combination, the kernel log input can be 
rechosen without stoppi ng and restarti ng thedaemon. For example, if the/proc filesystem isto beunmounted, thefollowing 
command sequenceshould beused: 

# kill -TSTP pid 

# umount /proc 

# kill -CONT pid 

N otationswill bemade in the system logswith log info priority documenti ng the start/stop of logging. 
FILES 

/proc/kmsg 

BUGS 

Probably numerous. Well-formed context diffsappreciated. 
AUTHOR 

D r. Greg Wettstein (greg%wind. uucp@piains.nodak.edu), Enjellic Systems D evelopment, Oncology Research D ivision 
Computing Faci I ity, Roger M arisCancer Center, Fargo, ND 58122. 

Versori 1.1, 28 January 1994 



lpc 

ipc— Li ne printer control program. 
SYNOPSIS 

lpc [command [argument ...]] 

D ESC RIPTIO N 

ipc isused by the system administrator to control theoperation of the line printer system. For each line printer configured in 
/etc/printcap, ipc may beused to 

■ D isable or enable a printer 

■ D isable or enable a printer's spool ingqueue 

■ Rearrangetheorder of jobs in aspoolingqueue 

■ Fi nd the status of pri nters and the r associ ated spooli ng queues and pri nter daemons 

Without any arguments, ipc prompts for commandsfrom the standard input. If arguments are supplied, ipc interprete the 
first argument as a command and the remai ni ng arguments as parameters to the command. The standard input may be 
redirected, causi ng ipc to read commandsfrom file. Commandsmay be abbrevi ated; thefollowing is the list of recognized 
commands: 

? [ command ... jheip [ command ... ] Pri nt a short descri ption of each command specified i n the argument 

list or, if no arguments are given, a list of the recognized commands. 

ic abort no ali - printer Termi nate an active spooli ng daemon on the locai host immediately 

and then disableprinting (preventing new daemons from being 
started by ipr) for the specified pri nters. 

ciean no ali - printer Remove any temporary files, data fi les, and control files that cannot 

beprinted (that is, they do notform a complete pri nter job) from the 
specified printer queues on thelocal machine 

disabie no ali - printer Turn the specified printer queues off. T his prevents new printer jobs 

from being entered into thequeuebyipr. 
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le down No ali - printer me s s a g e 



enable No ali - - printer 
exit, quit 

restart ali - printer 



start ali - printer 
status No ali - printer 
stop ali - printer 

topq printer [ j obnum ... ] [user 
up ali - printer 



Tum the specified printer queue off, disableprinting, and put messa ge 
in the printer status file. The messagedoesn't need to be quoted; the 
remai ni ngarguments are treated like echo(l). Thisisusually used to 
take a printer down and let others know why ipq(l) indicatesthe 
printer isdown and pri nt the status message. 
Enablespoolingon thelocal queue for the listed printers. Thisallows 
ipr(l) to put new jobsin the spool queue. 
Exitfrom ipc. 

Attempt to start a new printer daemon. This isuseful when some 
abnormal condition causes the daemon to dieunexpectedly leaving 
jobsin the queue. ìpq reportsthatthereisno daemon presentwhen 
thiscondition occurs. If the user is the super-user, tryto abortthe 
current daemon first (that is, kill and restart a stuck daemon). 
E nable pri nting and start a spooli ng daemon for the listed printers. 
D i splay the status of daemonsand queueson thelocal machine 
Stop a spool ing daemon after the current job compi etes and disable 
pri nting. 

Place the jobsin theorder listed at the top of the printer queue 
Enableeverythingand start a new printer daemon. U ndoes the effeets 
of down. 



FILES 

/etc/printeap 

/var/spool/* 

/var/spool/*/lock 



printer description file 
spool directories 
lockfilefor queue control 



SEEALSO 

lpd(8), lpr(l), lpq(l), lprm(l), printcap(5) 

DIAGNOSTICS 

?Ambiguous command 
?Invalìd command 
?Privileged command 



Abbreviation matches morethan onecommand. 
N o match wasfound. 
C ommand can be executed by root only. 



HI STORY 

Theipc command appeared in BSD 4.2. 



BSD 4.2, 16 March 1991 



lpd 

ìpd— Line printer spooler daemon. 
SYNOPSIS 

lpd [-1] [porti] 

DESCRIPTION 

ìpd is the li ne printer daemon (spool area handler) and is usuai ly invoked at boottimefrom therc(8) file. It makes a single 
passthrough theprintcap(5) fileto find out about theexisting printers and printsany filesleft after a crash. It then usesthe 
system calls i±sten(2) and accept(2) to receiverequeststo print filesin the queue, transfer fi lesto thespooling area, display 




thequeue, or removejobsfrom thequeua In each case, itforksachildto handletherequestsotheparent can continue to 
li sten for morerequests. 

Availableoptions: 

-ì The -ì flag causesipd to log vali d requests received from the network. This can beuseful for 

debugging purposes. 

port# The Internet port number used to rendezvouswith other processes is usuai ly obtained with 

getservbyname(3) but can bechanged with the por t# argument. 

Access control isprovided by two means. First, ali requests must come from oneof themachines listaci in the file /etc/ 
hosts.equiv or /etc/hosts.ipd. Second, if the rs capabi I ity isspecified in theprintcap entry for the printer beingaccessed, 
ipr requests are only honored for thoseusers with accountson the machine with the printer. 

Thefileminfree in each spool directory contai ns the number of disk blocksto leave f ree so that the li ne printer queuewon't 
completely fili the disk. T he mi nfree fi le can beedited with your favorite text editor. 

Thedaemon begins processing fi les after it hassuccessfully set thelock for exclusi ve access (described later) and scansthe 
spool directory for fi les beginningwith et. Lines in each et file specify filesto beprinted or non-printingactionsto be 
performed. Each such line begins with a key characterto specify whatto do with the remainder of the line: 



j Job name. String to beused for the job nameon theburst page, 

c Classification. String to beused for the classificati on lineon theburst page. 

l L iterai. The li ne contai ns identi fication info from the password fi le and causes the banner page 
to beprinted. 

t Title. Stringto beused asthetitleforpr(l). 

h H ost name. N ameof the machine whereipr was invoked. 

p Person. Login name of the perso n who invoked ipr. This is used to verify ownership by iprm. 

m Send mail to the specified userwhen the current print job completes. 

f Formatted file. N ameof afileto print which isalready formatted. 

1 Like f but passes control characters and does not make page breaks. 

p N ameof afileto print usingpr(l) asafilter. 

t Troff file. The filecontainstroff(l) output (cat photo typesetter commands). 

n D itroff file. The fi le contai ns devi ce independent troff output. 

r D VI file. T he fi le contai nsT ex I output DVI format from Standford. 

g Graph file. The fi le contai ns data produced by piot(3). 

c Cifplotfile. Thefilecontainsdata produced by cifpiot. 

v Thefilecontainsa raster image. 

r Thefile containstext datawith FO RTRAN carriage control characters. 

1 Troff font R. N ameof the font file to useinstead of the default. 

2 T roff font I . N ame of thefont f i le to use instead of the default. 

3 Troff font B. N ameof the font file to useinstead of the default. 

4 Troff font S. N ameof the font file to useinstead of the default. 

w Width. Changes the page width (in characters) used by pr(l) and thetextfilters. 

i Indent. The number of characters to indent the output by (in ASCII), 

u Unlink. N ameof fileto removeupon completion of printing. 

n Filmarne. T he name of the fi le that isbeing printed or a blank for the standard input (when ipr 
is invoked in a pipeline). 



If afilecannot beopened, a messageislogged viasysiog(3) usingthei_0G lpr facility. ìpd triesup to 20 ti mesto reopen a fi le 
itexpeetsto bethere, afterwhich it ski ps the fi le to beprinted. 
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ìpd usestiock(2) to provide occlusive access to thelock fi le and to prevent multiple daemonsfrom becoming active 
simultaneously. If thedaemon should bekilled or dieunexpectedly, thelock fileneed not beremoved. Thelock file is kept 
in a readable ASC II form and contai nstwo lines. The first istheprocessID of thedaemon and thesecond is the control 
filenameof thecurrent job being printed. Thesecond lineisupdated to reflect the current statusof ìpd for the programs 

lpq(l) and lprm(l). 



FILES 



/etc/printcap 

/var/spool/* 

/var/spool/*/minf ree 

/dev/lp* 

/dev/printer 

/etc/hosts.equiv 

/etc/hosts.lpd 



Printer descri ption file 

Spool di rectories 

M inimum free space to leave 

Line printer devices 

Socket for locai requests 

Lists machine namesallowed printer access 

Lists machine names allowed printer access but not under same admi ni strati ve control 



SEEALSO 

lpc(8), pac(l), lpr(l), lpq(l), lprm(l), syslog(3), printcap(5) 

4.2 BSD Line Printer Spooler M anual 
HI STORY 

An ìpd daemon appeared in Version 6, AT&T U N IX. 



BSD 4.2, 16 March 1991 



MAKEDEV 

makedev— C reates and maintainsfilesystem device entri es. 
SYNOPSIS 

MAKEDEV [ -vcdnhV ] device or devi ce-group names 

DESCRI PTION 

makedev isused to maintain the special filesystem entriesfound in /dev. It creates, or optional ly removes, oneor more device 
entri es. The names and devi cenumbers are defined in thedevinfo fi le (q.v.); site-specific confi guration isfound inthefile 
makedev. cfg. makedev itself has no knowledge of devi ce informati on. 

OPTIONS 



-v Verbose mode; print out exactly what's being done. 

-c Create; create the specified devices (default). 

-d Delete; rem ove the speci fi ed devices in stead of creatingthem. 

-n Do nothing; only print whatwould bedone. Implies -v aswell. 

■h Printausagemessage. 

-v Print the version string. 

Thefollowing targets are speci al : 

update Run makedev in update mode. T his reads the list of devices currently availablefrom 

/proc/devices and updates ali entriesin /dev to match the device numbersfound there. 



MAKEDEV 
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locai Run makedev to create locai devices. This option is obsolete and just printsawarning message. 

U se devinfo. locai and makedev. ctg to achieve the same results. 

FILES 

/etc/devinto D evice i nformation 

/usr/iocai/etc/devinfo. locai Locai device information 

/etc/devinto. locai Alternate location for locai device information 

/etc/makedev.ctg C onfiguration file 

makedev. cache C ached data for update 

/proc/devices The kernel 's list of current devices 

AUTHOR 

David A. H ol land (dhoiiand?husc. harvard.edu). Based on the older makedev shell script written by N ick H olloway. Addi- 
tional ideaswere contri buted by Rik Faith. 

NOTES 

The lalr(1) parser generator used to build makedev. c from makedev. syn is a commercial product. You won't beableto do a 
complete rebuild unlessyou haveit. 

SEEALSO 

devinfo(5), makedev. cfg(5) 

MAKEDEV 

makedev— C reates devices. 
SYNOPSIS 

ed dev; ./MAKEDEV -V 

ed dev; . /MAKEDEV [ -n ] [ -v ] update 

Cd dev; ./MAKEDEV [ -n ] [ -v ] [ -d ] devi ce ... 

D ESC RIFTIO N 

makedev isa script that creates the devices in /dev used to interface with drivers in the kernel. 

NotethatprogramsgivingtheerrorENOENT: no such file or directory usually means that the devicefile is missing, whereas 
enodev: No such device usually means the kernel does not have the driver configured or loaded. 

OPTIONS 

-v Printout versi on (actually RCS version information) and exit. 

-n D o not actual ly update the devi ces; just pri nt the actions that would be performed. 

-d D elete the devi ces. The mai n use for this f lag is by makedev itself. 

-v Beverbose. Print out the actionsasthey are performed. T hisis the same output as produced by -n. 

CUSTOMIZATION 

Becausethereiscurrently no standard ization in what names are used for system usersand groups, it is possi ble that you 
might need to modify makedev to reflectyour si te's setti ngs. N ear the top of the fi le isa mappingfrom devicetypeto user, 
group, and permissions. (Forexample, ali CD-ROM devices are set from the$cdrom variable.) If you wantto changethe 
defaults, this isthe section to edit. 
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DEVICES 

General Options 



update 

generic 
%std 



locai 

Virtual Terminals 



Serial Devices 



Thisonly works on kernel sthat have/proc/interrupts (introduced during l.l.x). Thisfileis 
scanned to seewhatdevices arecurrently configured into the kernel, and thisiscompared with 
the previous setti ngsstored in the fi le cai led devices. Devicesthatarenew sincethen or havea 
different major number arecreated, and thosethat areno longer configured aredeleted. 
Create a generic subset of devices. Thisis the standard devices, plusfloppy drives, vari ous hard 
drives, pseudo-terminals, console devices, basic serial devices, busmice, and printer ports. 
Standard devices. These are mem, accessto physical memory; kmem, accessto kernel virtual 
memory; nuli, nuli device (i rifinite sink); port, accessto I/O ports; zero, nuli bytesource 
(infinite source); core, symiink to /proc/kcore (for kernel debugging); full, alwaysreturns 
enospace on write; ram, ramdisk; tty, to access the controlling tty of a process. 
Thissimply runs makedev. locai. This is a script that can create any locai devices. 



consoie Thiscreatesthedevicesassociated with the console. This is the virtual terminalsttyx, wherex 

can befrom athough 63. The device ttya isthe currently active vt and isalso known as console. 
For each vt, therearetwo devices, vcsx and vcsax, which areused to generate screen-dumpsof 
thevt (thevcsx isjust thetext and vcsax i ncludes theattri butes). 



ttyS{0. .63} 



cyclades 



Pseudo Terminals 



Serial ports and correspondingdial-out device. For device ttysx, there isalso thedevicecuax, 
which isused to dial out with. This can avoid theneed for cooperative locks in simple 
situations. 

D ial-in and dial-out devices for the cyclades intelligent I/O serial card. The dial in device is 
ttycx and thecorresponding dial-out deviceiscubx. By default, devices for 7 lines arecreated, 
but this can bechanged to 15 by removingthecomment. 



pty[p-s] 



Parallel Ports 



Each possi bleargumentwi II create a bank of 16 master and slave pai rs. The current kernel (1.2) 
islimited to 64 such pai rs. The master pseudo-terminals are pty[p-s][0-9a-f] and theslavesare 

tty[p-s][0-9a-f]. 



ip 

par 

BusM ice 



Joystick Devices 



Standard parallel ports. The devices arecreated ipe, ìpi, and ip2. These correspond to ports at 
0x3bc, 0x378, and 0x278. H enee, on somemachines, the first printer port may actually beipi. 
Alternative to ip. Ports are named parx instead of ìpx. 



busmice The various bus micedevices. T his creates thefollowing devices: ìogimouse (Logitech bus 

mouse), psmouse (PS/2-style mouse), msmouse (M icrosoft Inport bus mouse), atimouse (ATI XL 
bus mouse) and jmouse (J -mouse). 



Disk Devices 



Joystick. Creates j se and jsi. 



fd[0-7] 



Floppy disk devices. Thedevicetdx isthedevicethatautodeteetstheformat, and theadditional 
devices arefixed format (whose size is indicated in thename). Theother devices are named as 



MAKEDEV 





fdxLn . T ne single letter L i dentiti es the typeor floppy disk (d =5.25 D D , ti =5.25 HD, 




n —3 R"nn u — 3 R" Ul n r-icupnì Thonnmhtyn rorirocontc tho rariaritv rtf that frtrm at 
D — J.D U U , H — J.J n U t E — j.J J. 1 Ile llUlllua n Icpicbclllb lllc LdpdLlLy Ul llldl IUI [lidi 




in I^R T h i ic rho cran HarH fri rm afe aro f hqcitl f^v hioan f h v n7ora frivui/i/ira anH cooon 
IN l\ D . 1 1 1 Ub LI le bldl 1 Udì U U 1 1 1 IdLb di c Tux CidbU, Tuxnitivlfcj, TuX L)/Vtì, TaXrn44W, dllU TOXt^oaW. 




For more information, see Alain Knaff'sfdutiis pack-age. 




DevicestdB* through td3* are floppy diskson the first controller, and devices td4* through fd7* 




are floppy diskson thesecond controller. 


hd[a-d] 


AT hard disks. The device hdx provi des access to thewholedisk, with the partitions being 




hdx [0-20]. The four primary partitions are hdxi through hdx4, with the logicai partitions being 




numberedfrom hdxsthough hdx 20. (A primary partition can bemadeinto an extended 




partition, which can hold four logicai partitions). By default, only the devices for four logicai 




r\ari"i fi 0 n c sro in ;*Ho X h 0 ofh ore ran ho m scio 1 inrn m monfi n n fh om 
pai LI LI Ul ìd al c 1 1 IdUc. 1 1 1 c U LI 1 ci b Lai 1 Uc 1 1 lailc Uy Ul 1LU 1 1 1 1 1 lei ILI 1 ILJ LI lei 1 1 . 




D rives hda and hdb are the two on the first controller. If usi ng the new 1 D E driver (rather than 




t~h a r\\r\ Ul l~ì ci ci \ /oc\ i~h ori :^ct d i^riri aro t~h o Ha; o d ci \ /oc oct t~h o croco et d^c» i co et i~co 1 1 oc T h oro 
Lllc UIU n U UN VciJ, Li lai nuC dllU nuu ale Lllc LWU UN vcb Oli Lllc bcLUNUai y LO 11 Li UN a . 1 llcbc 




rjp\/irpc ran alcn hp i iqpH fn arrpcK ID F ("D-ROM c; if i id nn fhp npw 1 D F d ri \/pr 

UCV 1 Ld L.QI i ai _JU UC UjCU LU ai_l_CjJ 1 \-> l_ \_ VJ l\U l"l J II U ZÌI i i u li 1 C 1 1 CVv 1 1 ' 1 U 1 1 V CI . 


xd[a-d] 


XT hard disks. Partitions are the sameaslD E disks. 


sd[a-h] 


SCSI hard disks. The parti ti ons are si mi lar to thelD E disks, but thereisa limit of 11 logicai 




partitions (sdx 5 through sdx 15). T his isto allow 8 SCSI disks. 


loop 


Loopback disk devices. These allow you to use a regular fi le as a block device. This meansthat 




i m ance nf fi I oc\/crom c rari rio m m i nroH anH i icoH ac n ri rrvi al X h i c rroatoc P Ho\/i roc i nnnn rh mi inh 
lllldycb Ul lllebyblclllb Ldll Uc IHUUIIlcU di 1 U Ubcu db Numidi. 1 lllb Ucdlcb o UcVILeb loopw UHUUyil 




100p7. 


Tape Devices 




St[0-7] 


SC SI tapes. This creates the rewinding tape device stx and the non-rewi nding tape device nstx . 


qic 


QIC-80 tape. The devices created arermts, ™ti6, tape-d, and tape reset. 


ftape 


F loppy driver tapes (Q 1 C -117). T here are four methods of access dependi ng on the floppy tape 




drive. Foreach of the access methods 0, 1, 2, and 3, the devi cesrttx (rewinding) and nrttx 




(nnn-roìft/i nrli nn\ aro rroatorl Fnr rrtmriatihiliri/ rlowirpc: f + a no anrl nf+ano aro cA/mlinkctn rftpi 

\IIUII 1 CVV 1 1 IUI 1 ly/ dICLICdLCU. TUI LUI I lUdLI Ul 1 1 ly, UCVILCbTTdpe dllU llTXdpe di C by 1 1 1 1 1 1 1 Kb LU ITIVI 




and nrfte. 


CD-ROM Devices 




SCd[0-7] 


SCSI CD players. 


sonycd 


Sony CDU-31A CD player. 


mcd 


M itsumi CD player. 


cdu535 


SonyCDU-535CD player. 


lmscd 


LMS/PhilipsCD player. 


sbpcd{,1 ,2,3} 


SoundBlaster CD player. The kernel iscapableof supporti ng 16 CD-ROM s, each of which is 




accessea as sbpca[0-9a-f ] . i nese are assignea i n groups or rour to eacn controller, sbpea is a 




symlinkto sbpedo. 


Scanner 




1 nn "i epa n 


1 onitprh SranM an^? and SranM an ?Sfi 


m1 05scan 


M i ict"oL* tiA 1 flR Ul ^ct dee ^ et et oc 
l v l UbLcK l v l 1UD n ailubLallilcT. 


ac4096 


AATol^ C olor I-I anHcrannor 

n4 1 cl\ ^- UIUI n ai lUbLdl II lei . 


Audio 




audio 


This creates the audio devicesused by the sound driver. These include mixer, sequencer, dsp, 




and audio. 


peaudio 


Devices for the PC Speaker sound driver. These are pemixer, pxsp, and peaudio. 
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M isrellaneous 



sg G eneri c SCSI devi ces. The devi cescreated aresgo through sg7. Theseallow arbitrary commands 

to besent to any SCSI device. This allows for querying information about the device or 
controlli ng SCSI devicesthat arenot oneof disk, tape, or CD-ROM (for example, a scanner or 
writableCD-ROM). 

fd To allow an arbitrary program to befed input from fi le descriptor x , use /dev/fd/x asthe 

filename. Thisalso createsBR/dev/stdin, BR/dev/stdout, and BR/dev/stderr. (Notethattheseare 
justsymlinks into /proc/seif/fd.) 

ibcs2 Devices (and symlinks) needed by the IBCS2 emulation. 

apm Devicesfor power management. 

dcf D river for DCF-77 radio clock. 

heiioworid Kernel modulesdemonstration device. Seethemodulessource. 

N etwork devi ces Linux used to havedevicesin /dev for controlli ng network devi ces, butthat is no longer the 

case. To seewhat network devicesareknown by the kernel, look at /proc/net/dev. 

SEEALSO 

Linux Allocateci Devices, maintained by H . Peter Anvin (peter.Anvin@iinux.org) 

AUTHOR 

N ick H olloway 

Linux, 14 August 1994 



mke2fs 

mke2f s— C reate a Linux second extended filesystem. 
SYNOPSIS 

mke2fs [ -c | -1 filename ] [ -b block-size ] [ -f f r a g me nt • s i z e ] 
[ -i bytes-per-i node ] [ -m reserved - bl ocks - percentage ] [ -q ][-v ][-S ] 
device [ bl ocks-count ] 

D ESC RIPTIO N 

mke2ts isused to create a Linux second extended filesystem on a device (usually a disk partition). devi ce is the speci al file 
correspondingto the device (such as/dev/ndxx). bl ocks-count isthenumberof blockson the device. If omitted, mke2fs 
autom ati cai ly f i gu res th e f i I esystem si ze. 

OPTIONS 

-b block-size Specify thesize of blocks in bytes. 

-c Check thedevicefor bad blocks before creati ng the filesystem using a fast read-only 

test. 

-t fragment-si ze Specify the size of fragments in bytes. 

-i bytes- per- 1 node Specify the bytes/inode ratio. mke2ts creates an inode for every by t es ■ pe r ■ i n o de bytes 

of space on the disk. This value defaults to 4096 bytes. bytes - per - i node must beat 
least 1024. 

- 1 f i i e n a me Read the bad blocks list from f i I e n a me . 

-m reserved- bi o c ks ■ pe r c e nt a g e Specify the percentage of reserved blocks for the super-user. This value defaults to 5 

percent. 

-q Quiet execution. Useful if mke2fs isrun in a script, 

-v Verbose execution. 
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■s W rite superblock and group descriptorsonly. Thisisuseful if ali the superblock and 

backup superblocksarecorrupted and a last-ditch recovery method is desi red. It 
causes mke2f s to reinitialize the superblock and group descriptors while not touching 
theinodetableand the block and inodebitmaps. Thee2fsck program should berun 
immediately after this option is used, and there is no guarantee that any data will be 
salvageable. 

AUTHOR 

This version of mke2fs has been written by TheodoreT'so (tytso9mit.edu). 
BUGS 

mke2fs acceptsthe -t option but currently ignoresit becausethesecond extended filesystem doesnot support fragmentsyet. 
There may besomeother bugs. Pleasereportthem to theauthor. 

AVAILABILITY 

rake2fs isavailablefor anonymous FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs. 

SEEALSO 

badblocks(8), dumpe2f s(8), e2f sck(8), tune2f s(8) 

Version 0.5b, N ovember 1994 



mkfs 

mkfs— Build a Linux filesystem. 
SYNOPSIS 

mkfs [ -V ][-t fstype ][fs-options ] filesys [ blocks ] 

DESCRIPTION 

mkfs isused to build a Linux filesystem on a device usuai ly a hard disk partition. f i i esys iseither the device name(such as/ 
dev/hdai, /dev/sdb2) or the mount point (such as/, /usr, /bome) for the filesystem. bi o c k s isthenumber of blocks to beused 
for the filesystem. 

The exit codereturned by mkfs iso on success and 1 on fai Iure. 

In actuality, mkfs is si mply a front end for the vari ous filesystem builders(mkfs. fstype) available under Linux. The fi lesystem- 
specific builder issearched for in /etc/fs first, then in /etc, and fi nal ly in the di rectories listed in thePATH environment 
variable. Please see the fi lesystem-specific builder manual pagesforfurther details. 



OPTIONS 

-V 

-tfstype 

fs-options 
-c 

-lf i I e ri a me 
-v 



Produce verbose output, includi ng ali fi lesystem-specific commandsthat areexecuted. 
Specifying this option morethan onceinhibitsexecution of any fi lesystem-specific commands. 
This is really only useful for testing. 

Specifi es the typeof filesystem to bebuilt. If not specified, thetypeisdeduced by searchingfor 
fi i esys in /etc/fstab and using the correspondi ng entry. If thetypecannot bededuced, the 
default filesystem type (currently minix) isused. 

Fi lesystem-specific optionsto be passed to thereal filesystem builder. Although not guaranteed, 
thefollowing options aresupported by most filesystem bui Iders. 
C heck the device for bad blocks before bui Idi ng the filesystem. 
Read the bad blocks list from f m e n a me . 
Produce verbose output. 
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BUGS 

Ali generic options must precede and not becombined with filesystem-specific options. Somefilesystem-specific programsdo 
notsupportthe -v (verbose) option nor return meaningful exit codes. Al so, somefilesystem-specific programsdo not 
automati cai ly detect the device size and require the blocks parameter to be specified. 

AUTHORS 

David Engel (david@ods.com), Fred N . van Kempen (waltjeUuwalt.nl.mugnet.org), and Ron Sommeling (sommeliasci.kun.nl). 

Themanual pagewasshamelessly adapted from Remy Card'sversion fortheext2 filesystem. 
SEEALSO 

fsck(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkf s . xiaf s(8) 

Version 1.9, Junel995 



mkf s 

mkfs— M akea Linux M IN IX filesystem. 

SYNOPSIS 

mkfs [ -c ] [ - nn a me I e n g t h ] [ -i i nodecount ] device si ze- i n- bl ocks 
mkfs [ -1 fi lena me ] devi ce size-in-blocks 

DESCRIPTION 

mkfs createsa Linux M IN IX filesystem on a device (usuai ly a disk partition). 

The device isusually of thefollowingform: 

/dev/hda[1-8] 
/dev/hdb[1-8] 
/dev/sda[1-8] 
/dev/sdb[1-8] 

T he s ze- i n- bi ocks parameter isthedesired sizeof thefilesystem in blocks. Thisinformation can bedetermined from the 
fdisk(8) program. 0 nly block counts strictly greater than 10 and strictly lessthan 65,536 areallowed. 

OPTIONS 

-c Check the device for bad blocks before creati ng thefilesystem. If any arefound, thecountis 

printed. 

-nnamei ength Specify the maximum length of filenames. N o space is al lowed between the -n and the 

n a me i e n g t h . Currently, the only allowable values areu and 30. 30 is the default, 
-i i nodecount Specify the number of inodes for the filesystem. 

-1 f i 1 e nenie Read the bad blocks list from f 1 1 e n a me . Thefilehasonebad block number per line. The count 

of bad blocks read is printed. 

EXIT CODES 

T he exit code returned by mkf s .minix is one of the following: 

0 No errors 

8 Operational errar 

16 U sage or syntax errar 

SEEALSO 

fsck(8), mkef s(8), ef sck(8), reboot(8) 



m kl ost+f ou n d 



AUTHOR 

LinusTorvalds (torvaids@cs.heisinki.fi). Errar code vai ues by Rik Faith (faithgcs.unc.edu). Inoderequestfeature by Scott 
H eavner (sdhepo.cwru.edu). Support for the filesystem valid flag by D r. Wettstein (greg%wind. uucp@piains.nodak.edu). 

Check to prevent mkfs of mounted filesystem and boot sector clearing by Daniel Quinlan (quinian@yggdrasii.com). 

Linux 0.99, 10 January 1994 

mklost+f ound 

mkiost+found— C reate a lost+found directory on a mounted Linux second extended filesystem. 
SYNOPSIS 

mklost+f ound 

D ESC RIPTIO N 

mkiost+found isused to create a lost+found directory in the cu rrent working directory on a Linux second extended filesystem. 
mkiost+f ound pre-allocates disk blocks to the directory to make it usable by e2fsck. 

OPTIONS 

Thereare none 

AUTHOR 

mkiost+found waswritten by Remy Card (card@masi.ibp.fr), thedeveloper and maintainer of theext2 fs. 

BUGS 

Thereare none :-) 

AVAILABILITY 

mkiost+found isavailablefor anonymOUS FTP from ftp.ibp.fr andtsx-11.mit.edu in /pub/linux/packages/ext2fs. 

SEEALSO 

e2fsck(8), mke2fs(8) 

Versi on 0.5b, N ovember 1994 

mkswap 

mkswap— Set up a Linux swap area. 
SYNOPSIS 

mkswap [ -c ] devi ce [si ze- n- bl ocks ] 

DESCRIPTION 

mkswap setsup a Linux swap areaon a device or in a file. 
The device is usuai ly of thefollowingform: 

/dev/hda[1 -8] 
/dev/hdb[1-8] 
/dev/sda[1-8] 
/dev/sdb[1-8] 
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T he si ze-i n-bi ocks parameter is the desi red sizeof thefilesystem in blocks. This information is determi ned automatically by 
mkswap if it isomitted. Block countsarerounded down so that the total size is an integer multiple ofthemachine's page size. 
Only block countsin therangeiniNcouNT. .maxcount areallowed. If the block count exceeds the maxcount, it istruncated to 
that value and awarningmessageisissued. 

T he mincount and maxcount valuesfor a swap area are 

MINCOUNT =10 * PAGE_SIZE / 1024 

MAXCOUNT = (PAGE_SIZE-10)*8 *PAGE_SIZE / 1024 

Forexample, on amachinewith 4KB pages(such asx86), weget 
mincount = 10 * 4096 / 1024 =40 
maxcount = (4096 - 10) * 8 * 4096 / 1024 = 130752 

Aseach block islKB, the swap area in this examplecould haveasizethat isanywherein therangefrom 40KB to 
127.6875M B. 

If you don't know the page size that your machineuses, you may beableto look it up with cat /proc/cpuinfo. 

Thereason for thelimit on maxcount i s that a single page isused to hold the swap bitmap at the start of the swap area, where 
each bit represents a single page. Thereason for the -10, is that the signature is swap -space - 10 characters. 

To set up a swap file, it is necessary to create that file beforerunning mkswap. A sequenceof commands similar to the 
following is reasonable for this purpose: 

# dd if=/dev/zero of=swapfìle bs=1024 count=8192 

# mkswap swapfile 8192 

# sync 

# swapon swapfile 

N ote that a swap file must not contai n any holes(so using cp(l) to createthefileisnot acceptable). 
0PTI0NS 

-c Check the device for bad blocks before creati ng thefilesystem. If any arefound, thecount 

isprinted. Thisoption ismeantto beused for swap partitions only and should not be 
used for regular fileslTo makesurethat regular filesdo not contai n bad blocks, the 
partition that contains the regular file should havebeen created with mkfs -c. 

SEEALS0 

fsck(8), mkf s(8), fdisk(8) 

AUTH0R 

LinusTorvaldS (torvaldsPcs.helsinki.fi) 

Linux 1.0, 8 February 1995 



mount, umount 

mount, umount— M ount and dismount fi lesystems. 
SYNOPSIS 

mount [-afrwuvn] [-t vfstype] 

mount [-frwuvn] [-0 remount [,...]] special j node 
mount [-frwun] [-t vfstype] [-0 opti 0 n s 1 special j node 
umount [ -an] [ -t vf st y pe ] 
umount special | node 



mount, unmount 
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DESCRIVO N 

The mount command callsthemount(2) system cali to prepare and graft a special device onto thefilesystem treeat thepoint 
node. Ifeither speci ai or no de arenot provided, the appropri ateinformation istaken from thefstab(5) file. The speci al 
keyword none can beused instead of a path or nodespecification.Thisisuseful when mountingtheproc filesystem. 

The system maintainsa list of currently mounted filesystems. If no argumentsaregiven to mount, thislist isprinted. 

Optionsavailablefor the mount command: 

-t Causeseverythingto bedoneexceptfortheactual system cali; if it'snotobvious, this 

"fakes" mounti ng the filesystem. This opti on isuseful in conjunction with the -v flag to 
determinewhat the mount command istryingto do. 
-o 0 ptions are specified with a -oflagfollowed by a comma-separated stringof options. 

N otethat many ofthese options are only useful when they appear in the/etc/fstab file. 
T he following options applyto any filesystem that isbeing mounted: 
Ali I/O to thefilesystem should bedoneasynchronously. 
C an be mounted with the -a option. 

U Se default options: rw, suid, dev, exec, auto, nouser, and async. 

Interpret character or block special deviceson thefilesystem. 
Permit execution of binari es. 

Can only be mounted explicitly (that is, the -a option does not cause the filesystem to 
be mounted). 

D o not interpret character or block special deviceson thefilesystem. This option is 
useful for a server that has filesystems contai ni ng special devicesfor architecturesother 
than itsown. 

Do not allow execution of any binarieson the mounted filesystem. This option isuseful 
for a server th at h as f i I esystem s co ntai n i n g bi n ari es f o r arch i tectu res oth er th an i ts own . 
Do not allow set-user-i denti fi er or set-group-identifier bitsto takeeffect. 
Forbid an ordinary (that is, non-root) user to mountthefilesystem. 
Atterri pt to remount an already-mounted filesystem. This iscommonly used to change 
the mount flags for a filesystem, especially to make a read-only filesystem writable. 
Mountthefilesystem read-only. 
M ount thefilesystem read-write. 

Allow set-user-identifier or set-group-identifier bitsto takeeffect. 
Ali I/O to thefilesystem should bedonesynchronously. 
Allow an ordinary user to mountthefilesystem. Ordinary usersalways have the 
following options activated: noexec, nosuid, and nodev (unlessoverridden bythesuper- 
user by using, for example, the following option line user, exec, dev, suid. 

T hefollowing options apply only to certain filesystems: 



async 
auto 

defaults 
dev 
exec 
noauto 

nodev 



nosuid 
nouser 
remount 



rw 

suid 
sync 
user 



case=va uè 
check=val ue 



none 
normal 



strict 



check=\ia ne 



Forthenpts filesystem, specify caseasiower or asis. 

Tellstheext2 filesystem kernel codeto do somemorecheckswhilethefilesystem is 
mounted. Currently (0.99.15), the following valuescan be specified with this option: 
N o extra check is performed by the kernel code. 

Theinodesand blocks bitmapsarechecked when thefilesystem is mounted (this is the 
default). 

In additi on to the normal checks, block deal location checks that the block tofreeis in 
the data zone. 

Forthemsdos filesystem, threedifferent levelsof speci fi city can bechosen: 
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relaxed 



normal 



strict 



conv=v a I y e 



binary 

text 

auto 



U ppercaseand lowercaseareaccepted and equivalent, long namepartsaretruncated (for 
example, veriongname.foobar become veryiong .t oo), leading and embedded spacesare 
accepted in each namepart (nameand extension). 

Like relaxed but many special characters(*, ?, <, spaces, and so on) arerejected. Thisis 
the default. 

Like normai, but names may not contai n long partsand special charactersthat are 
sometimesused on Linux but are not accepted by M S-D OS arerejected (+, =, spaces, 
and so on). 

Forthemsdos, hpfs, and iso9660 filesystems, specify fileconversion asbinary, text, or 
auto. The iso9660 filesystem also allowsvalueto bemtext. 
Themsdos filesystem can perform crlf<->nl (M S-D 0 S text format to U N IX text 
format) conversion in the kernel. Thefollowingconversion modesareavailable: 
N o translation is performed. This isthedefault. 
crlf<->nl translation is performed on ali file. 

crlf<->nl translation is performed on ali filethat don't haveawell-known binary 
extension. The list of known extensionscan befound at thebeginningof 

f s/msdos/misc . c (as Of 09913r, the list ÌS exe, coni, bin, app, sys, drv, ovl, ovr, obj, lib, 
dll, plf, are, zip, lha, lzh, zoo, tar, z, arj, tz, taz, tzp, tpz, gif, bmp, tif, gl, jpg, pcx, 
tfm, vf, gf , pk, pxl, and dvi). 

Programsthatdo computed iseeks won't likein-kernel text conversion. 

For filesystems mounted in binary mode, a conversion tool (fromdos/todos) isavailable. 

For the iso9660 fi lesystem, set the block size 

Seegrpid. 

Fortheiso9660 filesystem, set thecruftflagto y. Thisoption is available because there 
arebuggy premastering programsout there that leavejunk in the top byteof the fi le 
size. Thisoption clearsthetop byte but restri cts fi lesto 16M B maximum in theprocess. 
Forthemsdos filesystem, turn on thedebug flag. A version string and a list of filesystem 
parametersisprinted. (Thesedata are also printed if theparametersappearto be 
inconsistent.) 

Fortheext2fs filesystem, cause the kernel codeto display thefilesystem parameters 
when the filesystem is mounted. 
Fortheext2fs filesystem, specify the errar behavior: 

N o special action istaken on errors(except marking thefilesystem aserroneous). Thisis 
the default. 

Thefilesystem isremounted read only, and subsequentwritearerefused. 
When an errar isdetected, the system panics. 

For the msdos filesystem, specify either a 12-bit fat or a 16-bit fat. T his overrides the 
automatic FAT type detection routine Usewith caution! 
Forthemsdos and hpfs filesystems, give every file a gid equal to vai ue. 
Cause the ext2fs to usetheBSD behavior when creatingfile: File are created with the 
grouplD of their parent directory. 

Fortheiso9660 filesystem, specify mappingasoff or normai. In general, non-Rock 
Ridge discs haveall thefilenamein uppercase, and ali the filmarne nave a ;1 
appended. Themap option stri ps the ; 1 and makesthenamelowercase. (Seealso 

norock.) 

Fortheext2fs, turns off checking (seecneck=none). 

Cause the ext2fs to usetheSystem V behavior when creatingfile. Files are created 
with thegroup ID of the creati ng process, unlessthesetgid bit isset on the parent 
directory. This isthedefault for ali Linux filesystems. 



block=v a I ue 

bsdgroups 

cruft 



debug 



debug 

errors=val ue 
continue 

remount, ro 
panie 
fat=val ue 

gid=val ue 
B grpid 

map=v a I ue 



nocheck 
nogrpid 



mount, unmount 
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norock N ormai iso9600 filenamesappear in a 8.3 format (that is, D 0 S-like restri ctionson 

fi lename length), and in addition, ali charactersarein uppercase. Also there is no field 
for file ownership, protection, number of links, provision for block/character devices, 
and so on. 

Rock Ridgeisan extension to iso96ea that provi des ali of theseU N IX-like features. 
Basi cally, there are extensionsto each directory record that supply ali of theadditional 
information, and when Rock Ridgeisin use, the filesystem is indistinguishablefrom a 
normal U N IX filesystem (exceptthat it isread only, of course). 
The norock switch disablestheuseof Rock Ridgeextensions, even if available. (Seealso 

map.) 

quiet Forthemsdos filesystem, turn on thequiet flag. Attemptsto cnown or cnmod filesdo not 

yield errors, although theyfail. Usewith cauti on! 
sb=v a i ue Fortheext2 filesystem, usean alternate superbi ock located at block vai uè. vai ue is 

numbered in 1024- byte blocks. An ext2 filesystem usually hasbackupsof thesuperblock 

atblocksl, 8193, 16385, and so on. 

sysvgroups Seenogrpid. 

uid=vai ue Forthemsdos and npfs filesystems, give every file a uid equal to vai ue. 

umask=vai ne Forthemsdos and npfs fi lesystems, give every fi le a umask of vai ne. Theradix defaults to 

octal. 

The full set of optionsapplied is determi ned by first extracting the opti ons for the filesystem from thetstab table, then 
applyingany optionsspecified by the -o argument, and finally applyingthe -r or -w option. 

If themsdos filesystem detectsan inconsistency, it reportsan errar and sets the filesystem to read only. The filesystem can be 
madewritableagain by remounting it. 

-r Thefilesystem object isto bemounted read only. 

-t vf stype Theargumentfollowingthe -t isused to indicate the filesystem type. Thefilesystem 

types that are currently supported are listed in iinux/fs/fiiesystems.c: minux, ext, ext2, 

xiafs, msdos, hpf s, proc, nfs, iso9660, sysv, xenix, coherent. N Ote that that last three are 

equivalent and that xenix and coherent will beremoved at somepoint in thefuture; use 
sysv instead. 

The type minix is the default. If no -t option isgiven, or if the auto type is speci fi ed, the 
superblock is probed for thefilesystem type (minix, ext, ext2, and xia are supported). If 
thisprobefailsand /proc/fiiesystems exists, then ali the filesystems listed aretried, 
except for those label ed nodev (such asproc and nfs). 

N ote that the auto typemay beuseful for user-mounted floppies. For example, the mount 
command mountsall fi lesystems except those of type msdos and ext: 

mount -a -t nomsdos.ext 

-v Verbose mode. 

-w Thefilesystem object isto beread and write. 

-n M ount without writing in /etc/mtab. 

umount removesthespeci ai devicegrafted at point n o d e from thefilesystem tree. 
Optionsfortheumount command: 

-a Ali of the filesystems described in /etc/mtab areunmounted. 

-t vf stype Isused to indicate the actions should only betaken on filesystems of the specified type. 

M orethan one typemay be specified in acomma-separated list. The list of filesystem 
types can beprefixed with no to specify thefilesystem types on which no action should 
betaken. (See example for the mount command.) 
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FILES 

/etc/fstab Filesystem table 

/etc/mtab" Lock fi le 

/etc/mtab.tmp Temporary file 

SEEALSO 

mount(2), umount(2), fstab(5), swapon(8) 

BUGS 

It is possi blefor acorrupted filesystem to cause a crash. 

Some Linux fi lesystemsdon't support -o synchronous(theext2fs doessupport synchronousupdates(a la BSD ) when 
mounted with the sync option). 

The -o remount may not beableto changemount parameters (ali ext2fs parameters, except sb, are changeable with a 
remount, for example, but you can't changegid or umask for thedosfs). 

HI STORY 

A mount command appeared in Version 6, AT&T U N IX. 

AUTHORSAND CONTRIBUTORS 

The Linux mount command hasa long and conti nuing hi story. The following major releasesarenoted with thenameof the 
primary modifier: 

0.97.3: D Oug Q uale (quale@saavik. cs .wisc .edu) 
0.98.5: H J. Lu (hlu@eecs.wsu.edu) 

0.99.2: Rick Sladkey (jrs@worid.std.com) 
0.99.6: Rick Sladkey (jrs@worid.std.com) 
0.99.10: Stephen Tweedie(sct@dcs. ed. ac.uk) 
0.99.14: Rick Sladkey (jrs@worid.std.com) 

(Filesystem-specific informati on added to man pageon 27 N ovember 1993 by Rik Faith with alot of information and text 
from the following filesystem authors: Werner Almesberger, Eric Youngdale and RemyCard.) 

Linux 1.1, 8 February 1995 



mountd 

mountd— N FS mount daemon. 
SYNOPSIS 

/usr/etc/rpc. mountd [\-f\- -exports-file\] [\-dhnprv\] 
[ \ - -debug\ ] [ \ ■ -exports -f ile=f ile\ ] [ \ - -help\ ] 
[ \ ■ -allow-non-root\] [ \ - - re- export \] [ \ - -version \] 

D ESC RIPTIO N 

The mountd program isan N FS mount daemon. 

OPTIONS 

-t or - -exports -tue Thisoption specifies the exports file, I isti ng the ci ientsthat this server is prepared to 

serve and parameters to applyto each such mount (seeexports(5)). By default, exports 
areread from /etc/exports. 



named-xfer 
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-d Or - -debug 

■h Or --help 

-n Or - -allow-non-root 



■p Or - -promiscuous 
-r Or - - re-export 



-v Or - -version 



Log each transaction verbosely to thesysiog. 
Providea short help summary. 

Allow incoming mount requeststo behonored even if they do not originate from 
reserved IP ports. Someolder N FS client implementationsrequirethis. Somenewer 
N FS client implementationsdon't bel i ève i n reserved port checking. 
Put the server into promiscuous modewhere itwill serve any host on the network. 
Allow imported N FSfilesystemsto beexported. Thiscan beused to turn a machine 
into an N FS multiplier. Caution should beused when reexporting loopback N FS 
mounts because reenteri ng the mount point resultsin deadiock between theN FS client 
and the N FS server. 

Report the current version number of the program. 



SEEALSO 

exports(5), nfsd(8), ugidd(8C) 

BUGS 

The current implementation (stili) does not keep track of remote mounts. 
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named-xfer 

named-xfer— Ancillaryagent for inbound zonetransfers. 
SYNOPSIS 

named-xfer -z z o ri e _ t o_ t r a n s f e r -f d b _ f i I e -s seri al _ n o [ -d debugi evel ] 
[-1 debuglogfile ] [ - t t r ace_f i I e ] [ - p por t # ] [ -S ] nane server 

D ESC RIPTIO N 

named-xfer isan ancillary program executed by named(8) to perform an inbound zonetransfer. It is rarely executed directly 
and only by system administratorswho aretrying to debug a zone transfer problem. See RFC s 1033, 1034, and 1035 for 
moreinformation on thelnternet name-domain system. 

Optionsare 

-z Specifi es the nameof the zone to betransferred. 

-f Specifi es the nameof the fileinto which thezoneshould bedumped when it isreceived 

from the primary server. 

-s Specifi es the serial number of the current copy of thiszone. If the SO A RR you getfrom 

the primary server does not have a serial number higherthan this, the transfer isaborted. 

-d Print debugging information. A nu m ber af ter th ed determi nes the level ofmessages 

printed. 

-ì Specifi es a log file for debugging messages. The default issystem-dependent but is 

usually in /var/tmp or /usr/tmp. N ote that this only appi iesif -d is also specified. 

-t Specifi es a trace file that contains a protocol trace of the zone transfer. This isprobably 

only of interest to people debugging the nameserver itself. 

-p Useadifferent port number. The default is the standard port number asreturned by 

getservbyname(3) for Service "domain". 

-s Perform a restri cted transfer of only the SO A, N S records, and glueA records for the 

zone. The SO A record isnot loaded by named but isused to determi ne when to verify 
theN S records. Seethestubs di rective in named(8) for moreinformation. 
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Additional arguments aretaken asnameserver addressesin so-called "dotted-quad" syntaxonly; no hostnamesareallowed 
nere. At least oneaddressmust bespecified. Any additional addressesaretried in order if the first onefailsto transfer 
successfully. 

SEEALSO 

named(8), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 

1035, RFC 1123, N ame Server 0 perationsG uidefor BIN D 

26 junel993 



named 

named — Internet domain nameserver. 
SYNOPSIS 

named [ -d debugi evel ][-p po r t # [ /I oc a I por t # ] ] [ {-b} bootfile ][-q ][-r ] 

DESCRIPTION 

named is the Internet domain nameserver. See RFC s 1033, 1034, and 1035 for moreinformation on the Internet name- 
domain system. Without any arguments, named reads the default boot file/etc/named.boot, readsany ini ti al data, and listens 
forqueries. 

Optionsare 

-d Print debugging information. A nu m ber af ter th ed determi nes the level ofmessages 

printed. 

-p Use nonstandard port numbers. The default is the standard port number asreturned by 

getservbyname(3) for service "domain". T he argument can specify two port numbers 
separated by aslash (/), in which casethefirst port isthat used when contacting remote 
serversand thesecond oneisthe service port bound by the locai instanceof named. This 
isused mostly for debugging purposes. 

■ b Usean alternate bootfile This is optional and allowsyou to specify a file with a leading 

dash. 

-q Trace ali incomingqueries if named hasbeen compi led with qrylog defined. N otethat 

thisoption is deprecateci in favor of the boot file directiveoptions query-iog. 

-r Turnsrecursion off in the server. Answerscan comeonly from locai (primary or 

secondary) zones. Thiscan beused on root servers. N otethat thisoption isdeprecated 
in favor of the boot file directiveoptions no-recursion. 

Any additional argument istaken asthenameof the boot fi le If multiple boot files are specified, only thelast isused. 

The boot fi le contai ns information about where the nameserver isto get itsinitial data. Lines in thebootfilecannot be 
continued on subsequent lines. Thefollowing isa small example: 

; boot file for name server 

directory /usr/local/adm/named 

; type domain source host/file backup file 

cache . root. cache 

primary Berkeley.EDU berkeley.edu. zone 
primary 32. 128. IN-ADDR. ARPA ucbhosts.rev 

secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak 
secondary 6 .32. 128 . IN-ADDR. ARPA 128.32.137.8 128.32.137.3 cc.rev.bak 
primary 0.0 . 1 27. IN -ADDR .ARPA localhost . rev 



riamai 1335 

forwarders 10.0.0.78 10.2.0.78 
limit transfers-in 10 
limit datasize 64M 

options forward-only query-log fake-iquery 

The directory line causes the server to change its working di rectoryto the di rectory specified. Thiscan beimportantforthe 
correct processi ngof $include files in primaryzonefiles. 

The cache line specifies that data in root. cache isto beplaced in the backup cache. 

Its mai n use isto speci fy datasuch as locations of root domain servers. This cache isnot used during normal operation, but is 
used as "hints" to find thecurrent root servers. The fi le root. cache isin the same format asberkeiey.edu. zone. Therecan be 
morethan one cache fi le specified. The root. cache fileshould beretrieved periodically from ftp.rs.internic.net becauseit 
containsa list of root servers, and this list changes periodically. 

The first sample primary line states that the fi le berkeiey.edu. zone containsauthoritativedatafortheBerkeiey.EDu zone The 
fi le berkeiey.edu. zone contai ns data in the master fileformat described in RFC 883. Ali domain names are relative to the 
ori gin, in this case Berkeiey.EDu (seebelow for a moredetailed description). Thesecond primary li ne states that the fi le 
ucbhosts.rev contai ns authori tati ve data for the domai n 32.i28.in-addr.arpa, which isused to translate addresses in network 
128.32 to hostnames. Each master fileshould begin with an SOA record for the zone (seebelow). 

The first sample secondary li ne specifies that ali authoritative data under cc.Berkeiey.EDu isto be transferred from the 
nameserver at 128.32.137.8. If the transfer fai Is, ittries 128.32.137.3 and conti nuestrying the addresses, up to ten, listaci on 
this line. The secondary copy isalso authoritative for the specified domain. The first non-dotted-quad addresson this line is 
taken asafilenamein which to back up the transferred zone The nameserver loads the zone from this backup fileif it exists 
when it boots, providi ng a complete copy even if the master servers are unreachabl e. Whenever a new copy of the domain is 
received by automati c zone transfer from oneof the master servers, thisfileisupdated. If no filenameisgiven, atemporary 
fileisused and deleted after each successful zone transfer. Thisisnotrecommended becauseit isa needlesswasteof 
bandwidth. Thesecond sample secondary li ne states that the address-to-hostnamemapping for the subnet 128.32.136 should 
beobtained from the same list of master servers as the previous zone. 

Thetorwarders li ne specifies the addresses of sitewide servers that will accept recursivequeriesfrom other servers. If theboot 
fi le specifies one or more forwarders, then the server send sali queriesfor data not in the cache to the forwarders first. Each 
forwarder isasked in turn until an answer isreturned or the list isexhausted. If no answer isforthcomingfrom aforwarder, 
the server conti nuesas itwould havewithout thetorwarders lineunlessit isin torward-oniy mode. Theforwardingfacility is 
useful to cause a large sitewide cachete begenerated on a master and to reduce traffic over linksto outsi de servers. It can also 
beused to allow servers to run that do not have direct access to the Internet but want to look up exterior names anyway. 

The slave line(deprecated) isallowed for backward compati bility. Its meaning i s identi cai to options torward-oniy. 

Thesortiist line can beused to indicate networks that areto bepreferred over other networks. Queriesfor host addresses 
fromhostson the same network as the server receive responses with locai network addresses listed first, then addresses on the 
sort list, and then other addresses. 

Thextrnets di recti ve (not shown) can beused to implement primitive access control. If this di recti ve isgiven, your 
nameserver only answers zone transfer requestsfrom hoststhat areon networks listed in your xtrnets di recti ves. This 
directivemay also begiven astcpiist for compatibility with older, interim servers 

The include di recti ve (not shown) can beused to processthecontentsof some other file asthough they appeared in place of 
the include di recti ve Thisis useful if you have a lot of zonesor if you have logicai groupingsof zones that are mai ntai ned by 
different people. The include directivetakesoneargument, the nameof the file whosecontents areto beincluded. N 0 
quotes are necessary around the fi lename. 

Thebogusns di recti ve ( not shown) tei I s B I N D that no queries areto besentto the specified nameserver addresses (which are 
specified asdotted quads, not as domain names). Thisis useful when you know that somepopular server hasbad data in a 
zone or cache, and you wantto avoid contami nati on whiletheproblem is bei ng fixed. 

The limit di recti ve can beused to change Bl N D 's internai limits, some of which (datasize, for example) areimplemented 
by the system and others(such as transfers-in) by BIN D itself. The number following the limit namecan bescaled by 
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postfixinga k, m, or g for kilobytes, megabytes, and gigabytes respectively. datasize'sargument sets the process data size 
enforced by the kernel. N otethat not ali systems provide a cali to implement this; on such systems, the use of thedatasize 
parameter of umit resultsin awarning message. transfers-in'sargument isthenumber of named-xfer subprocessesthat 
BIN D will spawn at any onetime. transfers-per-ns'sargument is the maximum number of zonetransfersto besimulta- 
neously initiated to any given remote nam eserver. 

Theoptions directive introduces a Boolean specifier that changesthe behavior of BIN D . M orethan oneoption can be 
specified in a single directive. T he currently defi ned optionsareasfollows: no-recursion, which causesBIN D to answer with 
a referrai rather than actual data whenever it receivesaquery for a nameit isnot authoritativefor. Don't set this on a server 
that islisted in any host'sresoiv.conf file, no-fetch-giue keeps BIN D from fetching missinggluewhen constructing the 
"additi onal data" section of a responsi this can beused in conjunction with no-recursion to prevent BIN D 's cache from ever 
growing in size or becomingcorrupted. query-iog causesall queriesto belogged via sysiog(3). Thisisa lot of data; don't 
turn iton lightly. forward-oniy causes the server to query only its forwarders. Thisoption i s usuai ly used on amachinethat 
wantsto run a server but for physical oradministrativereasonscannot be given access to the Internet, fake-ìquery tei I s 
BIN D to send back a uselessand bogusreply to "inverse queries" rather than respond with an error. T his is hdpful if you 
havea lot of microcomputersor SunOS hosts or both. 

Themax-fetcn directive (not shown) isallowed for backward compatibility; its meaning isidentical to ìimit transfers-in. 
The master file consistsof control information and a list of resourcerecordsfor objectsin the zone of theforms: 

$INCLUDE <f i I enamexopt _d ornai n > 
$0RIGIN <d o ma i n> 

<do ma i n ><o pt _ 1 1 1 > <opt_ci ass ><type><resource_r ecord_dat a > 

domai n is . for root, @ for thecurrent origin, or a standard domain name. If domai n is a standard domain namethat does not 
end with ., thecurrent origin isappended to the domain. Domain namesendingwith . areunmodified. Theopt. domai n 
field isused to definean origin forthedatain an included file. It isequivalentto piaci ng a sorigin statement before the first 
lineof theincluded file. The field is optional. N éther theopt .domai n fi dd nor sorigin statementsin the included filemodify 
thecurrent origin for this fi le Theopt _tt field isan optional integer number for the ti me-to-li ve field. It defaultsto 0, 
meaning the minimum value specified in the SO A record for the zone. Theopt _ci ass field is the object addresstype; 
currently only onetypeissupported, 1 n, for objectsconnected to the D ARPA Internet. The type field contai nsoneof the 
following tokens; the data expected in the resource_ record, data field isin parentheses: 



a A host address (dotted quad). 

ns An authoritativenameserver (domain). 

mx A mail exchanger (domain), preceded by a preference value (0.. 32767) with lower 

numeric values representing higher logicai preferences. 
cname Thecanonical nameforan alias (domain). 

soa M arks the start of a zone of authority (domain of originati ng host, domain address of 

maintainer, a seri al number and the following parametersin seconds: refresh, retry, 
expire, and minimum TTi_(seeRFC 883)). 

null A nuli resource record (no format or data). 

rp A responsi bleperson for some domain name (mailbox, txt- referrai). 

ptr A domain namepointer (domain). 

hinfo H ost information (cpu_type, os_type). 



Resource records usuai ly end at the end of a line but may be conti nued acrosslinesbetween openingand closing parentheses. 
Commentsareintroduced by semicolonsand conti nueto the end of the line 

N otethat there are other resource record types, not shown here. You should consult the BIN D OperationsGU IDe(BOG) 
for the complete list. Some resource record types may havebeen standardized in newer RFC s but notyet implemented in 
thisversion of BIN D . 

Each master zone fi le should begin with an SOA record for the zone. A sampleSOA record follows: 



riamai 
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@ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. ( 

1989020501 ; serial 

10800 ; refresh 

3600 ; retry 

3600000 ; expire 

86400 ) ; minimum 

The SO A specifies a serial number, which should bechanged each timethe master file ischanged. N otethat the serial 
number can begiven asadotted number, but thisisa very unwisethingto do because the translati on to normal integers is 
viaconcatenation rather than multi pi ication and addition. You can speli out theyear, month, day of month, and 0..99 
versi on number and stili fi t inside the unsi gned 32-bit sizeof thisfield. It'struethat wewill haveto rethink thisstrategy in 
theyear 4294, but we're not worried about it. Secondary servers check the serial number at intervals specified by the refresh 
ti me in seconds; if the serial number changes, a zone transfer isdoneto load thenew data. If a master server can not be 
contacted when a refresh isdue, the retry ti me specifies the interval at which refresh es should beattempted. If a master server 
cannot becontacted within the interval given by the expi re ti me, ali datafrom thezone is discarded by secondary servers. 
The minimum value isthetime-to-live(TTL) used by recordsin the fi le with no explicit time-to-live value. 



T he boot fi le di recti ves domain and suttixes havebeen obsoleted by a moreuseful resolver-based implementation of suffixing 
for parti al ly qualified domain names. Theprior mechanismscould fail under a number of situati ons, especi ally when then 
locai nameserver did not have complete information. 

T hefollowing signals havethe specified effect when sent to the server processusingthekm(l) command: 



NOTES 



SIGIOT 



SIGSYS 



SIGINT 



SIGHUP 



SIGWINCH 



SIGTERM 



SIGUSR1 



SIGUSR2 



C auses server to read named.boot and reload the database. If the server isbuiltwith the 
forced reload compi le-ti me option, then sighup also causes the server to check the serial 
number on ali secondary zones. U sually, the seri al numbersareonly checked atthe 
SO A-specified intervals. 

Dumps the current database and cache to /var/tmp/named_dump.db. 

D umps stati stics data into /var/tmp/named.stats if theserver iscompiled with -dstats. 

Stati stics data isappended to the fi le. Some systems use sigabrt rather than sigiot for 

this. 

Dumpstheprofilingdata in /var/tmp if theserver iscompiled with profi li ng (the server 
forks, changes directories, and exits). 

Dumps the primary and secondary database files. Used to savemodified dataon 

shutdown if theserver iscompiled with dynamicupdatingenabled. 

Turnson debugging; each sigusri increments debug level (sigemt on older systems 

WÌthOUtSIGUSRl). 

T urns off debugging completely (sigfpe on older systems withoutsiGusR2). 

Toggles logging of ali incomingqueriesviasysiog(3) (requires server to havebeen built 

with the qrylog option). 



FILES 



/etc/named.pid 

/var/run/named.pid 

/var/tmp/named_dump.db 

/var/tmp/named.run 

/var/tmp/named.stats 



/etc/named.boot 



N ameserver configuration boot file 
TheprocessID (on older systems) 
TheprocessID (on newer systems) 
D ump of the nameserver database 
D ebug output 



N ameserver stati stics data 
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SEEALSO 

kill(l), gethostbynameO), signal(2), resolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 

1033, RFC 1034, RFC 1035, RFC 1123, N ame Server 0 perationsGU IDefor Bl N D 

20 Junel995 

named. reload 

named . reioad— C ause the nameserver to synchronize its database. 
D ESC RIPTIO N 

Thiscommand sendsasiGHUP to therunning nameserver. Thissignal isdocumented in named(8). 
BUGS 

It does not check to seeif the nameserver isactually runningand could use a stale pi d cache fi le, which may result in the 
death of an unrelated process. 

SEEALSO 

named(8), named . restart(8) 

26 Junel993 

named. restart 

named . restart— Stop and restart the nameserver. 
D ESC RIPTIO N 

T his command sends a sigkill to the running nameserver and then starts a new one. 
BUGS 

It does not check to seeif the nameserver isactually runningand could use a stale pi d cache fi le, which may result in the 
death of an unrelated process. 

It does notwait after killing the old server befo re starti ng a new one. Because the server could takesometimeto die and the 
new oneexperiencesafatal errar if the old oneisn't goneby the ti me it starts, you can beleft in a situation whereyou have 
no nameserver at ali. 

SEEALSO 

named(8), named . reload(8) 

26 Junel993 

ndc 

ndc— N amedaemon control interface. 
SYNOPSIS 

ndc di recti ve [ ... ] 



netstat 



1339 



DESCRIVO N 

Thiscommand al lows the nam eserver administrator to send various signalsto the nam eserver or to restart it. Zero or more 
directi ves may be given from thefollowing list: 

status D isplaysthecurrent status of named asshown byps(l). 

dumpdb Causes named to dump its database and cachete /var/tmp/named_dump.db (usestheiNT 

signal.) 

reioad C auses named to check the serial numbersof ali primaryandsecondaryzonesandto 

reload thosethat havechanged (usestheHUP signal.) 

stats Causes named tO dump itS Stati StiCS tO /var/tmp/named . stats (usestheiOT Or ABRT signal.) 

trace C auses named to increment its "traci ng level" by one. W henever the traci ng level is 

nonzero, trace informati on iswritten to / var/tmp/named. run. H igher traci ng levels result 
in moredetailed information (usestheusm signal). 

notrace Causes named tO Set itS "traci ng la/d" tO zero, ClOSing /var/tmp/named. run if it ÌSOpen 

(usestheusR2 signal). 

queryiog Causes named to toggle the "query logging" feature, which results in asysiog(3) of each 

incorri ingquery (usesthewiNCH signal). N otethat query logging consumesquitea lot of 
log file space This di rective may also be given asqryiog. 

start Causes named to bestarted as longasit isn't already running. 

stop Causes named to bestopped if it is running. 

restart Causes named to be ki lied and restarted. 



BUGS 

Argumentsto named arenot preserved by restart or known by start. Somemechanism for controlli ng the parameters and 
environment should exist. 

Implemented asash(l) script. 
AUTHOR 

P au I V i xi e ( I n tern et Software C on sorti u m ) 
SEE ALSO 

named(8), named . reload(8), named . restart(8) 

27 N ovember 1994 



netstat 

netstat— D isplay active network connections 
SYNOPSIS 

netstat [[-a ] [ -t | -u ] -w]] [-n ] -o] ] -x] [-c] 
netstat -r [-c] [-n] 
netstat -v 

DESCRIPTION 

netstat di splays the status of network connections on either TCP, UD P, or RAW socketsto the system. By default, netstat 
only displays status on thoseTCP socketsthat arenot in thensTEN state (that is, connections to active processes). To obtain 
information about the kernel routingtable, netstat may beinvoked with the opti on -r. A listingof internai U N IX 
connections can beobtained byinvoking netstat with the option -x. 
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netstat 'Sdisplay 

Proto 

Recv-Q 

Send-Q 

Locai Address 



Foreign Address 

(State) 

ESTABLISHED 
SYN SE NT 
SYN RECV 
FIN WAIT1 
FIN WAIT2 
TIME WAIT 
CLOSED 
CLOSE WAIT 
LAST ACK 
LISTEN 
UNKNOWN 



i ncludes the following information for each socket: 

The protocol (either TC P orUDP) used by thesocket. 

Thecount of bytes not copied by the user program connected to thissocket. 

T he count of bytes not acknowledged by the remote host. 

Thelocal address (locai hostname) and port numberof thesocket. U nlessthe -n switch 
isgiven, thesocket address isresolved to itscanonical hostname, and the port number is 
transl ated i n to th e co rrespo n d i n g servi ce n am e. 

The remote address (remote hostname) and port number of thesocket. Aswith thelocal 

address:port, the -n switch tums off hostname and servicename resolution. 

T he state of thesocket. Becausethereareno statesin RAW and usually no statesused in 

U D P, thisrow may beleft blank. Usually, thiscan beoneof several values 

Thesocket has an established connection. 

Thesocket i s acti vel y atterri pti n g to establish a connection. 

Theconnection isbeing initialized. 

Thesocket isclosed, and theconnection is shutting down. 

Connection isclosed, and thesocket iswaitingfor ashutdown from the remote end. 

Thesocket iswaiting after dose for remote shutdown re-transmission. 

The socket i s not bei ng used. 

The remote end has shutdown, waiting for the socket to dose. 

The remote end shut down, and thesocket isclosed. Waiting for acknowledgment. 

Thesocket islisteningfor incomingconnections. 

The state of thesocket isunknown. 



If netstat isinvoked with theoption -o, additional information isdisplayed after the state info. This information isshown 
likethis: keyword (time/backoff) and an optional asterisk. The keyword sh ows th e state of the timer belonging to thesocket, 
thetimedisplayed (in seconds) ishow long it will take the timer to expire, the backoff value indi cates the current retry count 
for data tran smi ssion, and the asterisk i ndi cates that this timer isin theexpiration queue. Thelatter might be removed in 
future but is helpful for debuggi ng the T C P-C ode for now. 

Invoked with theoption -x, netstat displaysa list of ali acti ve U N IX internai communication sockets. 
netstat 'sdisplay includesthefollowing information for each socket: 

The protocol (usually UN IX) used by the socket. 
T he reference count (attached processes via this socket). 
Theonly known flagto me isso accepton (displayed asAcc); otherwise, left blank. 
so accepton isused on unconnected sockets if their corresponding processes are waiting 
foraconnectrequest. 
T here are several types of socket access: 
The socket isused in Datagram (connectionless) mode. 
Thisisastream (connection) socket. 
The socket isused as a raw socket. 
Thisoneserves reliably delivered messages. 
Thisisa sequential packet socket. 

Thissocket type isused asa Linux-specific way to get packetsat thedev (kernel) levd. It 
isassumed to beused to writethingssuch asRARP (Reverse Address Resolution 
Protocol) and similar thi ngs on theuser levd. 
unknown W ho ever knows, what future will bri ng; just fi 1 1 in here :-) 

state Thisfield will contain oneof thefollowing keywords: 

free Thesocket is not allocated. 



Proto 

RefCnt 

Flags 



Type 

SOCK DGRAM 
SOCK STREAM 
SOCK RAW 
SOCK RDM 
SOCK SEQPACKET 
SOCK PACKET 
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listening Thesocket is listening fora connection request. 

unconnected Thesocket isnot connected to another one 

connecting T he socket i s about to establish aconnection. 

connected T he socket i s connected. 

disconnecting Thesocket isdisconnecting. 

unknown T his state should never happen. 

patti This displays the pathname that the corresponding processes attached to thesocket. 
The network routing table {invoked with netstat -r) showsup thefollowing information: 



Destination net/address 



Gateway address 
Flags 



RefCnt 

Use 

Iface 

OPTIONS 



FILES 



/proc/net/tcp 
/proc/net/udp 
/proc/net/raw 
/proc/net/unix 



The destination address of a resolved host or hand-entered network isdisplayed. U nless 
theoption -n isgiven, thehostsor nets are resolved. An entry named default showsup 
the default route for the kernel. 

If thereisno asterisk (*) displayed, any data isrouted to thededicated gateway. 

Possi ble routing flags are 

u This route isusable. 

g Destination is a gateway. 

h Destination is a host entry. 

n Destination is a Net entry. 

r Routewill be rei nstated after timeout. 

d Thisoneiscreated dynamically (by redirection). 

m This one ismodified dynamically (by redirection). 

Referencecount for this route. 

How manytimesthisroutewasused yet. 

This is the name of the i nterf ace wh ere th i s route bel o n gs. 

D isplay information about ali I nternet sockets, such asTCP, UDP, and RAW, 
including those sockets that are listening only. 

Generate a continuous listing of network status: network status is displayed every second 
until the program isinterrupted. 

Causes netstat notto resolvehostnamesand servi ce nameswhen displaying remote and 

locai address and port information. 

D isplay timer states, expiration times, and backoff state. 

D isplay kernel routing table. 

D isplay information about TC P sockets only, including those that are listening. 

D isplay information about UDP sockets only. 

Print version information. 

D isplay information about raw sockets. 

D isplay information about UNIX domain sockets. 



TCP socket information 
UDP socket information 
RAW socket information 
UNIX domain socket information 
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/proc/net/route Kernel routing informati on 

/etc/ services T he services translati on 

BUGS 

N one report ed yet (5/20/93). 
AUTHORS 

Thenetstat user interface waswritten by Fred Baumgarten (dceiqeinsui .etec.uni-karisruhe.de). The man page is basi cai ly 

by M att Welsh (mdw@tc.cornell.edu). 

Cohesive Systems, 20 M ay 1993 



makeactive, makehistory, newsrequeue 

makeactive, makehistory, newsrequeue— ToolstO recover U Senet databases 

SYNOPSIS 

makeactive [ -m ] [ -o ] 

makehistory [ -b ][-f fi I e n a me ][-i ][-n ][-o ][-r ][-s size ] 
[ - T t mp d i r ] [ -u [ -v] ] 

newsrequeue [ -aactive ][-h history ][-ddays ] [ -1 ] [ - n newsf eeds ] [i nput ] 

D ESC RIPTIO N 

makeactive invokesfind(l) to get a list of ali di rectories in the news spool tree, /news/spooi. It discards directories named 
ìost+found aswell asthosethat havea period in them. It scansali other di rectories forai I-numeri c fi lenames and determi nes 
the highest and lowest number. The program's output isaset of active(5) file li nes. B ecause thereis no way to know if a 
group is moderated or disabled, thefourth fi eld of ali entri esisy. Also, mid-level di rectories that aren't newsgroupsarealso 
created asnewsgroupswith no entri es. (Forexample, thereis a comp.sources.unix group, but no comp.sources.) 

If the -o flag isused, makeactive readsan existing active file for the list of group names and just renumber ali groups. It 
preserves thefourth field of the active file if one ispresent. T hi sisanalogousto thectiinnd(8) renumber command, except 
that innd(8) should bethrottled or not running. Do not use this flag with output redirected to the standard active fi le! 

If the-m flag isgiven, then makeactive attemptsto adjust the highest and lowest articlenumberswherever possi ble. If articles 
arefound in a newsgroup, thenumbers reflect whatwasfound. If no articles are found in a newsgroup, the high number 
from the old fileiskept, and thelow number is setto one more than the high number. This flag may only beused if the -o 
flag isused. 

makeactive exitswith nonzero status if any problemsoccur. A typical way to use the program iswith thefollowing /bin/sh 
commands: 

ctlinnd throttle "Rebuilding active file" 
TEMP=${TMPDIR - / tmp} /act$$ 
if [ -f /var/lib/news/active ] ; then 
if makeactive -o >${TEMP} ; then 
mv ${TEMP} /var/lib/news/active 

fi 

else 

if makeactive >${TEMP} ; then 

# Edit to restore moderated 

# and aliased groups. 

mv ${TEMP} /var/lib/news/active 

fi 

fi 

ctlinnd reload active "New active file" 



makeactive, makehi story, newsrequeue 
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makehistory rebui Ids the history(5) text file and theassociated dbz(3) database. The default nameof the text file is 
/news/iib/history; to specify a different name, usethe-f flag. makehistory scanstheactive(5) fileto determinewhich 
newsgroup directories within thespool directory, /news/spooi, should bescanned. (If agroup isremoved, butits spool 
directory stili exists, makehistory ignoresit.) The program readseach filefound and writesa history linefor it. If the -b flag 
isused, then makehistory removesany articles that do not havevalid M essage-ID headersin them. 

After the text file iswritten, makehistory bui Ids the dbz database. If the -f flag isused, then the database fi les are named 
file, dir and fiie.pag. If the -f flag isnotused, then atemporary link to the name history. n ismadeand the database fi les 
arewritten as history. n.pag and history. n. dir. I f the -o flag isused, then the link is not madeand any existing history fi les 
areoverwritten. If the old database exists, makehistory usesitto determi ne the sizeof the new database. To ignoretheold 
database, usethe -i flag. Using the-o flag implies the -i flag. The program also ignoresany old database if the -s flag isused 
to specify the approxi mate num ber of entri es in the new database Accurately speci fying the sizeisan optimization that 
createsa more efficient database. (T he size should betheestimated eventual sizeof the fi le, typically the sizeof the old file.) 
For more informati on, seethediscussion of dbzfresh and dbzsize in dbz(3). 

If the -u flag isgiven, then makehistory assumesthat innd isrunning.lt pauses the server whi le scanning and then sends 
addhist commands (see ctiinnd(8)) to the server for any article that is notfound in the dbz database. The command 
makehistory -bu isuseful after a system crash to delete any mangled articles and bri ng the arti de database back into a more 
consistent state. If the-v flag isused with the-u flag, then makehistory putsacopy of ali added lineson its standard output. 

Toscan thespool directory without rebuilding the dbz fi les, use the -n flag. If used with -u, the server isnot paused whi le 
scanning. To just build the dbz filesfrom an existing text file use the -r flag. The -i or -s flagscan beuseful if thereareno 
valid dbz filesto use. A typical way to usethisprogram iswith thefollowing /bin/sh commands: 

ctlinnd throttle "Rebuilding history file" 
ed /news/lib 

if makehistory -n -f history. n ; then 
else 

echo Error creating history file! 

exit 1 

fi 

# The following line can be used to retain expired history. 

# It is not necessary for the history file to be sorted. 

# awk ' NF==2 { print; }' <history »history.n 

# View history file for mistakes. 

if makehistory -r -s 'wc -1 <history' -f history. n; then 

mv history. n history 

mv history . n . dir history. dir 

mv history. n.pag history. pag 

fi 

ctlinnd go " 

makehistory needsto create a temporary file that contai nsone linefor each article it fi nds, which can becomevery large. This 
fileiscreated in the /tmp directory. The tmpdir environmentvariablemay beused to specify a different directory. Alterna- 
ti vely, the-T flag may beused to specify atemporary directory. In addition, thesort(l) that isinvoked duri ng the build 
writes large temporary fi les (often to /var/tmp, but seeyour system man pages). If the-T flag isused, then the flag and its 
valuearepassed to sort. 0 n most systems, this changes the temporary directory that sort uses. If used, this flag and itsvalue 
arepassed on to the sort (1) command that is invoked during the build. 

makehistory does not handle symbolic links If the news spool area is split across multiple partitions, thefollowing commands 
should probably berun beforethedatabaseisregenerated: 

ed /news/spool 

find . -type 1 -name '[1-9]*' -print | xargs -t rm 



M akesureto run thecommand on ali the appropriate partitions! 
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newsrequeue can beused to rewrite batchfiles after a system crash. It operates in two modes. In the first mode, it first reads 
the a c t i ve and newsf eeds (5) filesto determine where the different newsgroups areto bedistributed. To specify alternate 
locationsforthesefiles, use the -a or-n flags. Itthen opensthehi story database. To specify a different file, use the -h flag. 

Once the files are opened, newsrequeue reads from thespecified input fi le or standard input if no fileisspecified. Each line 
should haveasingleM essage-ID, surrounded in angle brackets; any other text on thelineisignored. Forexample, the 
hi story file {or a trailing subset of it) isacceptable inputto the program operati ng in this mode. If the -d flag isused, then 
only articlesthatwerereceived within thespecified numberof daysareprocessed. 

newsrequeue usesthefirst two fields of the newsf eed entry— the sitename and theexciudes field and thepatterns and 
distribs field. It ignores ali flags in the third field except for the n field and also ignoresthefourth field altogether. 

Thesecond mode isused if the-i flag isused. In this mode, it reads from thespecified input fi le or standard input if no file 
is specifi ed. Each li ne should look likean innd log entry. It parses entri es for accepted articles, looksup the M essage-ID in 
the h i story database to get thefilename, and then scans the list of sites. 

In either mode, the output of newsrequeue consistsof onelinefor each arti de that should beforwarded. Each such line 
contai ns the M essage-ID, thefilename, and the list of sites that should receive the arti de. The output issuitablefor piping 
into fileohan(8). 

HISTORY 

W ritten by Rich $alz (rsaizeuunet.uu.net) for InterN etN ews. 
SEE ALSO 

active(5), ctlinnd(8), dbz(3), f ilechan(8), history(5), innd(8), newsfeeds(5) 



news.daily 

news.daiiy— Do regular U sen et system admi nistration 
SYNOPSIS 

news.daily [ keyword . . . ] 

innwatch [ -t s I eept i me ] [ - f c ont r o I f il e ] [ -1 I ogf i I e ] 
expirerm file 

inncheck [ -v ][-pedantic ][-perms [ -fi x ]][-noperms ][file. 



DESCRIVO N 

news.daily performs a number of important U senet admi n i strati ve functions. This includes produci ng a status report, 
removingold news articles, processing log files, rotati ng the archived log files, renumberingtheactivefile, removingany old 
socket files found in the firewall directory, and col lecti ng the output. This program should be run under the news 
administrator'sID, notasroot. 

By default, news.daily performsall its functions and mai Is the output to the news admi nistrator, usenet. By specifying 
keywordson thecommand line, it ispossibleto modify the functions performed, aswell as changetheargumentsgiven to 

expire(8) and expireover(8). 

news.daily should berun once a day, typically out of cron(8). It may berun moreoften, but such invocations should at least 
usethenorotate keyword to prevent the log files from being processed and rotated too fast. 

Theshiock(l) program isused to prevent simultaneousexecutions. 

The followi ng keywordsmay be used: 

deiayrm Thisusesthe-z flag when invoking expire and expireover. The namesof articles to be 

removed arewritten to atemporary fi le and then removed after expiration by cai I i ng 

expirerm. 



newsdaily 
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nostat 



noexpire 



noexplog 



flags='expire\args 



nologs 



Thiskeyword disables the status report generated by innstat (seenewsiog(8)). W ithout 
thiskeyword, the status report isthefi rst function performed, just priorto obtainingthe 

news.daily lock. 

By default, expire isinvoked to remove old newsarticles. Using thiskeyword disables 
thisfunction. 

expire usually appends information to /var/iog/news/expire.iog (see newsiog(5)). Using 
thiskeyword causes the expire output to behandled aspartof news, daiiy's output. It 
hasno effect if thenoexpire keyword isused. 

By default, expire isinvoked with thean argument of -vi. U sing thiskeyword changes 
the arguments to those speci fi ed. Be careful to use quotes if multiple arguments are 
needed. This keyword hasno effect if thenoexpire keyword isused. 
After expiration, scaniogs(8) isinvoked to processthelogfiles. Using this keyword 
disables ali log processi ng functions. 

By default, log processing includes rotati ng and cleaningout logfiles. Using this 
keyword disables the rotati ng and cleaning aspect of the log processing. The logfiles are 
only scanned for information and no contents are altered. Thiskeyword hasno effect if 
the nologs keyword is used. 

Thiskeyword disables the ctiinnd(8) renumberoperation. U sually, the low watermark 
forali newsgroups(seeactive(5)) is reset. 

By default, any socket ctiinnd socket that hasnot been modified fortwo daysis 
removed. Using this keyword disables thisfunction. 

news.daily usually sends a mail messagecontaining theresultsto theadministrator. 
Using this keyword causes thismessageto besentto stdout and stderr instead. Usually, 
ali utilitiesinvoked by the script havetheir stdout and stderr redirected into a file. If the 
fileisempty, no messageissent. 

The expireover program iscalled after expiration to purgetheoverview databases. 
expireovernargs 1 If the expireover keyword isused, this keyword may beused to specify theflagsto be 
passed to expireover. If the deiayrm keyword isused, then the default valueis-z and the 
list of deleted files; otherwise, the default value is-s. 

The program specified bythegiven path isexecuted just before any expiration isdone. 
A typical useisto specify an alternate expiration program and use thenoexpire keyword. 
M ultipleprogramsmay be specified; they areinvoked in order. 

Thenorotate keyword is passed on to scaniogs if it isinvoked. expirerm is a script that removesa list of files. The specified 
file lists thefiles. It issorted and then fed into a pi pel ine responsi ble for doing the removal, usually fast™(8). If thereseemed 
to bea problem removi ng the files, then mail issent to the news administrator. If therewereno problems, then fileis 
renamed to /var/iog/news/expire.iist where it is kept (for safety) until the next day's expirati on. 

innwatcn isa script that cari bestarted at newsboottime. It periodically— every si e e pt i me seconds— examinestheload 
averageand thenumber of freeblocksand inodeson the spool partition, asdescribed by its control file, innwatcn. cti(5). If 
theload getstoo high or the disk getstoo full, it throttles the server. W hen thecondition restores, it unblocks the server. In 
addition, on each passthrough the loop, it checksthe specified log fi le to seeif it hasbeen modified and sends mail to the 
news administrator if so. It i s usually a good ideato set this to thesysiog(3) file that receives criticai news messages. Upon 
reca pt of an interrupt signal, innwatcn reports its status in the fi le /news/nb/ innwatcn. status. 

inncneck isa peri(l) script that verifies the syntax and permissions of ali InterN etN ews configurati on files. If no files are 
specified, it checks ali files. A filmarne may befollowed by an equal sign and a path to indicatethepathnameto use for the 
file. For example, newsfeeds=/tmp/nf checks the syntax of a new newsfeeds(5) without requiring it to be instai led. If the-v 
flag isused, it prints status information asit checks each file If the-pedantic flag isused, it checks the files for omissionsthat 
arenot stri ctly erro rsbut might indicate a confi guration errar. 

If any fileis specified, only the permissions on those files are checked. The -noperms flag suppresses this check. If the -perms 
flag isused, the script verifies the ownership and permissions of ali files. The -fix flag can also beused so that the output can 
beexecuted asashell script. 



norenumber 



nomail 



expireover 
expireoverf lags= 



/full/path 
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HI STORY 

news.daiiy and thismanual pagewerewritten by Landon Curt N oli (chongo9toad.com) and Rich $alz (rsaiz@uunet.uu.net). 
inncneck waswritten by Brendan Kehoe(brendaniacs. widener.edu) and Rich. 

innwatch was written by M ike C OOper (mcooper0usc.edu) and (kre@munnari. oz.au). 

SEEALSO 

active(5), ctlinnd(8), expire(8), fastrm(8), newslog(5), newslog(8), innwatch. ctl(5), shlock(l) 



newslog 

newsiog— M ai ntenance of U senet log files 
SYNOPSIS 

scanlogs [ norotate ][nonn ] 
writelog name text. . . 
innstat 

tally.unwanted 
tally. control 
innlog.awk 



DESCRIVO N 

scaniogs summarizes the i nformation recorded in the inn log files (seenewsiog(5)). By default, italso rotatesand cleansout 
thelogs. It isusually invoked by the news. daiiy(8) script. 

Thefollowing keywordsareaccepted: 

norotate U sing this keyword disables the rotati ng and cleaning aspect of the log processing: 

Thelogs files are onlyscannedforinformation and no contents are altered. 

nonn Usually, thenn log file is scanned and rotated. U sing this keyword disables this 

function. 

If scaniogs isinvoked morethan once a day, the norotate keyword should beused to prevent premature log cleaning. 

The writelog script isused to writea log entry or send it as mail. The name parameter specifies the name of the log file where 
theentry should bewritten. If it istheword mail, then theentry ismailed to thenewsadministrator, Usenet. The data that 
is written or sent consistsof the text given on thecommand line, followed by standard input indented by four spaces. 
shiock(l) isused to avoid simultaneous updatesto a single logfile. 

The innstat script printsasnapshot of the inn system. It di splays the operati ng mode of the server, aswell as disk usageand 
the status of ali log and lock files. 

Therest of the seri pts descri bed here are usually invoked by scaniogs. They parse log files that aredescribed in newsiog(5) 
and the server's article log fi le described in innd(8). 

tally.unwanted script parses the article log fileto update the cumulative list of articles posted to unwanted newsgroups, 

unwanted.log. 

taiiy. control reads its standard input, which should bethenewgroup.log and rmgroup.iog log files. It updatesthecumulative 
list of newsgroup creationsand deleti ons, control. log. 

innlog.awk isan awk(l) script that summarizes the activity that innd and nnrpd(8) report to sysiog. 



HISTORY 

Written by Landon Curt N oli (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 



nnrpd 




SEEALSO 

innd(8) newslog(5), news . daily(8), nnrpd(8) 

nfsd 

nf sd— NFS servi ce daemon. 
SYNOPSIS 

/usr/etc/rpc .nfsd [ \ -f \exports-f ile\ ] [ \ -dhnprv\ ] 
[\--debug\][\--exports-file=fi I e\] [\--help\] 
[ \ - -allow-ndn-root\] [ \ - - re- export \] [ \ - -version\] 

D ESC RIPTIO N 

The nfsd program isan N FS servi ce daemon that handles client filesystem requests. U nlike nfsd on someother systems, nfsd 
operatesasa normal user-level process. The server also differsfrom other N FS server implementations in that it mountsan 
enti re file hierarchy not limited Py thePoundariesof physical filesystems. Theimplementation allowstheclients read-only or 
read-wri te access to the fi le hierarchy of the server machine. 

Themountd program startsan anci Mary user-level mount daemon. 
OPTIONS 

-f Or - -exports-file 

-d Or - -debug 
-h Or --help 
-n Or - -allow-non-root 

-p Or - -promiscuous 
-r Or --re-export 



-v Or - -version 

SEEALSO 

exports(5), mountd(8), ugidd(8C ) 

AUTHORS 

M ark Shand wrote the originai unfsd. Don Becker extended unfsd to support authentication and allow read-write access and 
called it nnfs. Rick Sladkey added host matching, sbowmount -e support, mountd authentication, metd support, and ali the 
portabi lity and configuration code. 

13 October 1993 

nnrpd 

nnrpd— N N T P server for on-campus hosts. 



Thisoption specifies the exports file, I isti ng the ci ients that this server is prepared to 
serve and parametersto applyto each such mount (seeexports(5)). By default, exports 
areread from /etc/exports. 
Log each transaction verPosely to thesysiog. 
Providea short help summary. 

Allow incoming N FS requests to Pehonored even if they do not originate from reserved 
IP ports. Someolder N FS client implementations requi re this. Somenewer N FS client 
implementations don't believe in reserved portchecking. 
Put the server into promiscuous mode whereit servesany host on the network. 
Allow imported N FSfilesystemsto Peexported. Thiscan Peused to turn a machine 
into an N FS multiplier. Caution should Peused when re-exporting loopPack N FS 
mountsPecausere-entering the mount point resultsin deadiock Petween the N FS client 
and the N FS server. 

Report the current version numPer of the program. 



Part V 1 1 1 : Admi ni strati on and P ri vi I eged Commands 



SYNOPSIS 

nnrpd [ -r reason ][-s title paddi n g ][-S host ][-t ] 

DESCRIVO N 

nnrpd i san N N TP server for newsreaders. It accepts commands on its standard input and respondson its standard output. 
It isusually invoked by innd(8) with those descri ptors attached to a remote client connection. 

If the-r flag isused, then nnrpd rejects the incomi ng connection giving reason asthetext. Thisflag isused by innd when it is 
paused orthrottled. 

Unlike innd, nnrpd supports ali N NTP commands for user-oriented reading and posting. 

nnrpd usesthe nnrp.access(5) fileto control who isauthorized to access the U sen et database. It al so rejects connetti onsif the 
load average isgreaterthan 16. 

Aseach command isreceived, nnrpd triesto changeitsargv array so that ps(l) printsthecommand beingexecuted. To get a 
full display, the-s flag may beused with a long stri ngas itsargument, which isoverwritten when the program changes its 
title. 

On exit, nnrpd reports usage statistics through sysiog(3). 

If the-t flag isused, ali client commands and initial responsesaretraced by reporti ng them in sysiog. Thisflag is set by innd 
under the control of thectiinnd(8) trace command and istoggled upon recei pt of a sighup; seesignai(2). 

If the-s flag isused, ali posti ngs are forwarded to thespecified host, which should be the master N NTP server. Thisflag is 
set by innd if it isstarted with the-s flag. 

nnrpd can accept multimedia posti ngs that follow the MIME standard aslong assuch postings are also acceptableasSM TP 
messages. Seethediscussion of theM IM E headersin inn.conf(5). 

PROTOCOL DIFFERENCES 

nnrpd i mplements the N NTP commands defi ned in RFC 977 with thefollowing differences 

■ Theinave command isnot implemented. Users should be usi ng the post command to post arti cles. 

■ The slave command isnot implemented. This command hasnever been fui ly defi ned. 

■ The list COmmand may befollowed by the optional word active.times, distributions, distrib.pats, newsgroups, or 

overview.tmt to get a list of when newsgroups where created, a list of vali d distributions, a file specifyi ng default 

di stri buti on patterns, a one-per-l ine descri ption of thecurrent set of newsgroups, or a listi ng of theoverview.fmt(5) file. 

The command list active isequivalentto the list command. Thisisacommon extension. 

■ Thexndr, autninfo user, and authinfo pass commands are i mplemented. T hese are based on the reference U N IX 
implementation; no otherdocumentation isavailable. 

■ A new command, xpat neader range|MessageiD pat [morepat . . . ], is provided. T he first argument is the case- in sen si ti ve 
nameof theheader to besearched. Thesecond argument iseither an article range or a single M essage-ID as speci fi ed in 
RFC 977. Thethird argument is a wiidmat(3)-style pattern; if there are additional arguments, they arejoined together 
separated by a single space to form the complete pattern. This command issimilarto thexndr command. It returnsa 221 
responsecode, followed by thetext responseof ali article numbersthat match the pattern. 

■ Theiistgroup group command isprovided. Thisisacomment extension. It isequivalentto thegroup command, except 
that the reply is a multi-line response contai ning the list of ali article numbers in the group. 

■ Thexgtitie [group] command isprovided. This extension isused by ANU-N ews. It returnsa 282 reply code, followed 
by a one-li ne descri ption of ali newsgroups that match the pattern. The default is thecurrent group. 

■ Thexover [range] command is provided. It returns a 224 reply code, followed by the overview data for the specified 
range; the default isto return the data for thecurrent article. 

■ Thexpatn MessageiD command isprovided; see innd(8). 

■ The date command isprovided; this is based on thedraft N NTP protocol revision. It returnsa one-li ne response code 
of 111 followed by theGMT date and timeon the server in the form YYYYMHDDhhmms s . 
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HI STORY 

Written by Ri eh $alz (rsaizeuunet.uu.net) for InterN etN ews. 0 verview support added by Rob Robertson 
(roMvioiet. berkeiey.edu) and Rich in January 1993. 

SEEALSO 

ctlinnd(8), innd(8), inn.conf(5), nnrp.access(5), signal(2), wildmat(3) 

nntpsend 

nntpsend— Send U senet articlesto remote site. 
SYNOPSIS 

nntpsend [ -d ][-p ][-r ][-S ][-s s i z e ][-t timeout ] 
[ - T t i me I i mi t ] [s i t e n a me f q d n ] ... 

D ESC RIFTIO N 

nntpsend is a front end that i nvokes innxmit(l) to send U senet articles to a remote N N T P site 

Thesitesto befed may bespecified by givingsi tenerne f q d n pairson thecommand line If no such pairsaregiven, nntpsend 
defaultsto the informati on given in the nntpsend. cti(5) configfile. 

T he s tename should be the name of the site as specified in thenewsfeeds(5) file Thefqdn should bethehostname 
or IP addressof the remote site. An innxmit islaunched for siteswith queued news Ali innxmit processesare 
spawned in the background and the script waitsforthem ali to finish befo re return ing. Output issentto the fi le 
/var/iog/news/nntpsend.iog. To avoid overwhelmi ng the locai system, nntpsend waitsfiveseconds beforespawning 
each child. Theflag -a isalways given asaflagto innxmit. 

nntpsend expeets that the batchf i le for a site i s named /news/spooi/out . going/s t e n a me . To prevent batchf i le corrupti on, 
sniock(l) isused to "lock" thesefiles. 

The-p, -r, -s, -t, and -Tflagsarepassed on to the child innxmit program. N otethat if the-pflag isused then no connection 
ismadeand no arti ci es are f ed to the remote site. It isuseful to havecron(8) invoke nntpsend with thisflag in case a site 
cannot bereached foran extended peri od of time. 

If the-s flag isused, then shrinkfiie(l) isinvoked to perform atail truncation on thebatchfileand theflag ispassed to it. 

When si tenerne f q d n pai rs are gi ven on thecommand line, anyflags given on thecommand completely describehow innxmit 
and shrinktiie operate. W hen no such pairsaregiven on thecommand line, then theinformation found in nntpsend. cti 
becomes the default flags for that site. Any flags given on the command line override the default flags for the site. 

For example, with thefollowing control file 

nsavaxierehwon.nsavax.gov: : -S -t60 
group70:group70.org: : 
walldrug:walldrug.com:1m: -T1800 -t300 

Thecommand 

nntpsend 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax (none) -a -S -t60 

group70 (none) -a -t180 

walldrug 1m -a -T1800 -t300 
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Thecommand 

nntpsend -d -T1200 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax (none) -a -d -S -T1200 -t60 

group70 (none) -a -d -T1200 - t 1 80 

walldrug 1m -a -d -T1200 -t300 

Thecommand 

nntpsend -s 5m -T1200 nsavax erehwon.nsavax.gov group70 group70.org 

will result in thefollowing: 

Sitename Truncation Innxmit flags 
nsavax 5m -a -T1200 -t180 

group70 5m -a -T1200 -t180 

Rememberthat-a isalways given, and -t defaultsto 1 so. 
HISTORY 

Written by Landon Curt N oli (chongo?toad.com) and Ri eh $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

innxmit(l), newsf eeds(5), nntpsend . ctl(5), shrinkf ile(l) 

nslookup 

nsiookup— Q uery I nternet nameservers interactively. 
SYNOPSIS 

nslookup [ -option ... ] [ host-to-fi nd | -[server ]] 

D ESC RIPTIO N 

nsiookup isa program to query Internet domain nameservers. nslookup hastwo modes: interactiveand non-interactive. 
Interactivemodeallows the user to query nameservers for informati on about various hosts and domai ns or to print a list of 
hostsin a domain. Non-interactive mode isused to print just the name and requested information for a host or domain. 

ARGUMENTS 

Interactive mode isentered in thefollowing cases: 

■ W hen no arguments are given (the default nameserver is used) 

■ When the first argument isa hyphen (-) and thesecond argument is the hostname or Internet addressof a nameserver 

N on-interactive mode isused when the name or Internet addressof the host to belooked up is given as the first argument. 
The opti onal second argument specif ies the host name or address of a nameserver. 

Theoptionslisted under the set command can bespecified in the .nsiookuprc fi le in the user's home directory if they are 
listed oneper line. Optionscan al so bespecified on thecommand lineif they precede the arguments and are prefixed with a 
hyphen. For example, to change the default query typeto host information, and theinitial timeout to 10 seconds, type: 

nslookup -query=hinf o -timeout=10 
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INTERACTIVE COMMANDS 

Commands may be i nterru pted at any timeby typing Ctrl+C . To exit, typeCtrl+D (EOF) or typeexit. Thecommand-line 
length must belessthan 256 characters. To treat a built-in command as a hostname, precede itwith an escape character (n). 
N otethat an unrecognized command is interpreted asa hostname. 

host [server] Look up information for host using the current default server or using s e r ver if 

speci fi ed. If host is an I nternet address and the query type is a or ptr, the name of the 
host isreturned. If host isa name and does not nave a trai li ng peri od, the default 
domain nameisappended to the name. (Thisbehaviordependson the state of the 

set options domain, srchlist, defname, and search). To look up a host not in thecurrent 

domain, append a peri od to the name. 

server domai n, iserver domai n C hange the default server to domai n. iserver uses the i ni ti al server to look up informa- 
tion aboutd ornai n , whereas server uses the current default server. If an authoritative 
answer can't befound, thenamesof servers that might nave the answer arereturned. 

root C hanges the default server to the server for the root of the domai n name space. 

Currently, the host ns.internic.net isused. (This command isasynonym for iserver 
ns.internic.net.) The name of the root server can bechanged with the set root 
command. 

finger [name ][> fi i e n a me ] , Connectswith the finger server on thecurrent host. Thecurrent host isdefined when 

finger [name][» menarne] a previous lookup for a host was successful and returned address information (seethe 

set query-type= a command). name is optional . > and » can be used to redi rect output 

in the usuai manner. 

is [opti o n ] domain [ > f i i e n a me ] , Listthe information availablefor domain, optionally creating or appending to 
is [option] domain [»fiiename] f i i ena me . T he default output contai ns hostnames and their I nternet addresses. opt i o n 

can beoneof thefollowing: 

-t querytype Listsall records of the specified type (see 

querytype). 

-a Listsaliasesof hosts in the domain. Synonym for 

-t CNAME. 

-d Listsall recordsforthedomain. Synonym for 

-t ANY. 

-h ListsCPU and operating system information for 

the domain. Synonym for -t hinfo. 

-s Listswell-known servicesof hosts in the domain. 

Synonym for -t wks. W hen output is directed to a 
file, hash marksareprinted forevery 50 records 
received from the server. 

view menarne Sorts and lists the output of previous is commands 

with more(l). 

heip, ? Printsabrief summaryof commands. 

exit Exits the program. 

set keyword [=vai ue] Thiscommand isused to changestate information 

that affects the lookups. V ali d keywords are 

ali Printsthe current vai uesof the frequently used 

optionsto set. Information about thecurrent 
default server and host is also printed. 
ciass=vai ne C hange the query class to oneof thefollowing: 

in The Internet class. 

chaos T he Chaos class. 
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hesiod TheM IT Athena H esiod class. 

any Wildcard (any of theabove). 

T he class specifies the protocol group of theinformation. (Default = in, abbrevi ation = 

ci.) 

[no]debug Turn debugging modeon. A lot more informati on isprinted about the packet sentto 

the server and the resulti nganswer. (D efault =nodebug, abbreviati on =[no]deb.) 

[no]d2 Turn exhaustive debugging modeon. Essentially, ali fields of every packet are printed. 

(D efault =nod2.) 

domain=name C hange the default domain nameto n a me. The default domain nameisappended to a 

lookup request dependi ng on the state of thedefname and search opti ons. The domain 
search list containsthe parentsof the default domain if it hasat least two components in 
its name. For example, if the default domain iscc.Berkeiey.EDu, thesearch list is 
cc.Berkeiey.EDu and Berkeiey.EDu. U sethe set srchiist command to specify a different 
list. Use the set ali command to display the list. (Default =valuefrom hostname, 
/etc/resoiv.cont, or localdo-main, abbreviation =do.) 

srchlist=namel /name 2 /. . . C hange the default domain nametO namel and the domain search list tona mei, name 2, 

and so on. A maximum of sixnamesseparated by slashes (/) can bespecified. For 

example, set srchlist=lcs. MIT.EDU/ai. MIT.EDU/MIT.EDU SetSthedomain tO lcs.MIT.EDU 

and thesearch listto thethreenames. T hi s command overri des the default domain 
name and search list of the set domain command. Use the set ali command to display 
the list. (Default =valuebased on hostname, /etc/resoiv.cont, or local-domain, 
abbreviation = srcni.) 

[nojdefname If set, append the default domain nameto asingle-component lookup request (that is, 

onethatdoesnot contain aperiod). (Default = detname, abbreviation =[no]def.) 

[no]search If the lookup request contains at least one period but doesn't end with atrailingperiod, 

append the domain namesin the domain search listto the request until an answer is 
received. (Default = search, abbreviation =[no]sea.) 

ponzai uè C hange the default TC P/U D P nameserver port to vai ne. (Default =53, abbreviation = 

po.) 

querytype=vai uè, type=vai ne C hange the type of information query to oneof thefollowing: 



a Thehost'slnternetaddress. 

cname Thecanonical nameforan alias. 

hinfo ThehostCPU and operati ng system type. 

minfo Themailboxor mail list information. 

mx The mail exchanger. 

ns T he nameserver for the named zone. 

ptr T he host name if the query i san I nternet address; otherwise, the pointer 

to other information. 

soa Thedomain's"start-of-authority" information. 

txt Thetext information. 

uinfo Theuser information. 

wks T he supported well-known services. 



Other types (any, axfr, mb, md, mf, null) aredescribed in the RFC -1035 document. 
(D efault =a, abbreviations = q, ty.) 
[no] recurse Teli the nameserver to query other servers if it does not have the information. (D efault = 

recurse, abbreviation = [no] ree.) 

retry=number Set thenumber of retri es to n u mb e r . When a reply to a request isnot received within a 

certain amount of time(changed with set timeout), thetimeout period isdoubled and 
the request is resent. T he retry value controis how many times a request is resent before 
givingup. (Default =4, abbreviation =ret.) 



overchan 
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root=host 

timeout=number 

[no]vc 

[no]ignoretc 



Changethenameof the root server to host . Thisaffectsthe root command. (Default = 

ns.internic.net, abbrevi ation = ro.) 

Changetheinitial timeout interval for waiting for a reply to nu mbe r seconds. Each retry 
doubles the timeout peri od. (Default =5 seconds, abbrevi ation =u.) 
Always use a virtual circuitwhen sending requeststo the server. (Default =novc, 
abbreviation =[nojv.) 

Ignore packet truncation errors. (Default = noignoretc, abbreviation = [no]ig.) 



DIAGNOSTICS 

If the lookup request was not successful, an errar message isprinted. Possible errors are 
Timed out 



No response from server 
No records 



Non-existent domain 
Connection refused, 
Network is unreachable 
Server failure 

Refused 
Format error 

FILES 

/Etc/Resolv.Conf 
SHOME/ .nslookuprc 
/usr/share/misc/nslookup. help 



The server did not respond to a request after acertain amount of time(changed with 
set timeout=va( ne) and a certai n number of retries (changed with set retry=vai ue). 
N 0 nameserver isrunningon the server machine. 

The server does not have resource records of the current query type for the host, 
although the hostname is valid. The query type isspecified with the set querytype 
command. 

Thehost or domain namedoesnot exist. 

The connection to the name or finger server could not bemadeat the current time. 
T his error commonly occurs with is and finger requests. 

The nameserver found an internai inconsistency in its database and could not return a 
valid answer. 

The nameserver refused to servi ce the request. 

The nameserver found that the request packet was not in the proper format. It may 
indicate an error in nsiookup. 



Initial domain name and nameserver addresses. 
User'sinitial options. 
Summary of commands. 



ENVIRONMENT 

HOSTALIASES 
LOCALDOMAIN 



Filecontaining host aliases. 
0 verri des default domain. 



SEEALSO 

resoiver(3), resoiver(5), named(8), RFC 1034 "Domain Names- Conceptsand Facilities," RFC 1035 "Domain Names- 
Implementation and Specification" 

AUTHOR 

Andrew Cherenson 

24 junel990 



overchan 



overchan— U pdate the news overview database. 
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SYNOPSIS 

overchan [ - D dir ] [ -c ] [f i I e . . . ] 

D ESC RIFTIO N 

overchan reads article data from fi les or standard input if none are specified. (A si ngle dash in the fi le list meansto read 
standard input.) It usesthis information to update the news overview database, overchan isdesigned to beused by 
InterN etN ewsor theC Newsmkov packagesto update the database as the artides come in. The database for each newsgroup 
isstored in afilenamed .overview in anewsgroup directory within the overview database tree. 

overchan locks the database fi le (by lockingan auxiliary file) before appendi ng the new data. To purge data after articleshave 
been expired, seeexpireover(8). 

By default, overchan processes its i nput asan inn overview stream written asawo entry in the newsfeeds(5) file: 

overview: * : Te ,WO: /news/bin /overchan 

T his data consists of a lineof text separated into two parts by a tab. T he first part isa list of ali relative pathnameswhere the 
article has been written with a single space between entri es. The second part is the data to be written into the overview file, 
except thattheinitial article number is omitted. 

To process the output of themkov(8) program, usethe-c flag. T his format isdescribed in thenov distribution. 
The-D flag can beused to speci fy where the databases are stored. The default directory is/news/spooi. 

HISTORY 

Written by Rob Robertson (robevioiet.berkeiey.edu) and Rich $alz (rsaizeuunet.uu.net) for InterN etN ews. 
SEEALSO 

newsf eeds(5), newsoverview(5), newsoverview(8) 



pac 

pac— Printer/ pi otter accounting information. 
SYNOPSIS 

pac [-P printer] [-c] [-m] [ - p p r i c e ] [-s] [-r] [name ...] 

DESCRIPTION 

pac reads the printer/ plotter accounting fi les, accumulating the number of pages (the usuai case) orfeet (for raster devices) of 
paper consumed by each user and printing how much each user consumed in pages orfeet and dollars. 

Optionsand operandsavailable 

-p pri nter Accounting isdoneforthenamed printer. Usually, accounting isdone for the default 

printer (sitedependent), or the valueof the environment variable printer isused. 

-c Flag causes the output to besorted by cost; usually, theoutput issorted alphabetically 

by name. 

-m Flag causes the hostnameto beignored in the accounting file. T hi sai lows for a user on 

multiple machinesto haveall hisprinting chargesgrouped together. 
-p pri ce T he valueprice isused for the cost in dollars instead of the default valueof 0.02 or the 

pri Ce Speci fi ed in /etc/printeap. 

-r Reverse the so rting order. 

-s Accounting information issummarized on the summary accounting fi le; thissummari- 

zation isnecessary becauseon a busy system, the accounting file can grow by several 
li nes per day. 



pcnfsd 



1355 



FILES 



/var/account/?acct 
/var/account/?_sum 
/etc/printcap 



Stati stics are only printed forusersnamed; usually, stati stics are printed forevery user 
who hasused any paper. 



Raw accountingfiles 
Summary accounting files 
Printer capabi lity dataPase 



SEEALSO 

printcap(5) 

BUGS 

Therelationship Petween thecomputed priceand reality isasyet unknown. 
HI STORY 

Thepac command appeared in BSD 4.0. 



BSD 4.2, 16 March 1991 



pcnfsd 



pcnfsd— (PC )N FS authentication and print request server 
SYNOPSIS 

/usr/etc/rpc. pcnfsd 

AVAILABILITY 

This program isfreely redi stri Putable. 

DESCRIPTION 

pcnfsd isan RPC serverthatsupportsONC clientsonPC (DOS, OS/2, M acintosh, and other) systems. ThispagedescriPes 
versi on 2 of the pcnfsd server. 

rpc. pcnfsd may Pe started from /etc/rc. locai orPytheinetd(8) superdaemon. It readstheconfiguration file 
/etc/pcnfsd.conf if present and then servicesRPC requests directed to program numPer 150001. This releaseof the pcnfsd 
daemon supports Poth version 1 and version 2 of the pcnfsd protocol. Consulttherpcgen source file pcnfsd. x for detailsof 
the protocol s. 

The requests serviced Py pcnfsd fall into threecategories: authentication, printing, and other. Only the authentication and 
pri nti n g servi ces h ave ad m i n i strati ve si gn i f i can ce. 

AUTHENTICATION 

When pcnfsd receives a pcnfsd auth or pcnfsd2 auth request, it "logsin" the user Py validatingtheusernameand password 
and returni ng the corresponding U ID, GIDs, home directory, and umask. If pcnfsd was Puilt with thevmp compi le-ti me 
option, italso appends a record to thewtmp(5) dataPase. If you do notwantto record PC loginsin thisway, you should add a 
lineof theform 

wtmp off 

tO the /etc/pcnfsd.conf file. 

By default, pcnfsd only allows authentication or print requests for userswith U ID s in the range 101 to 60002. (This 
correspondsin svr4 to the range for non-system accounts.) To overridethis, you may add a lineof theform 
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uidrange r a n g e [ ,r ange ] . . . 

to the /etc/pcnfsd.conf file. H ere, each r ange isof theform u i d or ui d -ui d, indicatingan inclusive range. 
PRINTING 

pcnfsd supportsa printing model based on the use of N FS to transfer the actual printdatafrom the client to the server. The 
client system issuesa pcnfsd_pr_init or PCN-FSD2_PR_iNiTrequest, and the server returnsthepath to a spool directory that the 
client may use and which isexported by N FS. pcnfsd creates a subdirectory f or each of itsclients: T he parent directory is 
usually /usr/spooi/pcnfs and the subdirectory is the hostname of the client system. If you want to use a different parent 
directory, you should add a lineof theform 

spooldir pat h 

tO the /etc/pcnfsd.conf file. 

Once a client has mounted the spool directory using N FS and hastransferred print datato a file in this directory, it issuesa 
pcnfsd_pr_start or pcnfsd2_pr_start request. pcnfsd handlesthis, and most other print-related requests, by constructing a 
command based on the printing servi cesof the server operati ng system and executing thecommand using the identity of the 
PC user. Becausethisinvolvesset-user-ID privileges, pcnfsd mustberun asroot. 

Every print request from the client i ncludes the nameof the printer that i sto beused. In Linux, thisnamecorrespondsto a 
printer definition in the/etc/printcap(5) database. If you want to define a non-standard way of processing print data, you 
should define a new printer and arrange for the client to print to this printer. There aretwo waysof setti ng up a new printer. 
Thefirst i nvolves the addition of an entry to /etc/printcap(5) and thecreation of filtersto perform therequired processing. 
T his is outside the scope of this discussion. In addition, pcnfsd includesa mechanism by which you can define virtual 
printersknown onlyto pcnfsd clients. Each printer is defined by a linein the /etc/pcnfsd.conf fileof thefollowingform: 

printer n a me alias -for command 

name is the name of the pri nter you want to define, ai i as- for is the nameof a "real" printer that correspondsto this printer. 
Forexample, a request to display the queue for nameistranslated into thecorresponding request for the pri nter ai i as- f or . If 
you have defined a printer in such a way that there is no "real" printer to which itcorresponds, use a single - for this fidd. 
(See the definition of the pri nter test for an example.) command is a command that wi II beexecuted whenever a file is printed 
on name. This command isexecuted by the shell at /bin/sn using the -c option. For complex operati ons, you should 
construct an executable shell program and invoke that in command. 

Considerthefollowingsample /etc/pcnfsd.conf file: 

printer rotated lw /usr/local/bin/enscript -2r $FILE 
printer test ■ /usr/bin/cp $FILE/usr/tmp/$HOST$USER 

If a client system printsajob on the printer rotated, the utility enscript isinvoked to pre-process thefile$FiLE. In this case, 
the -2r option causesthefileto be printed in two-column rotated format on the default PostScript printer. If the client 
requests a list of the print queue for the pri nter rotated, the pcnfsd daemon trans! ates this into a request for a listing for the 
pri nter iw. 

The printer test isused only for testi ng. Any file sent to this printer is copi ed into /usr/tmp. Any request to list the queue, 
check the status, and so on of printer test isrejected becausetheai as-f or isspecified as -. 



pi i pconfi g 



RECO NFIGU RATIO N 

pcnfsd detectswhen printers are added or deleted and rebuilds its list of valid printers. To do this, it checksthe modification 
timeof /etc/printcap. H owever, it doesnot monitor the file /etc/pcnfsd.conf for updates; if you changethisfile, it is stili 
necessary to kill and restart pcnfsd so the changes can take effect. 

FILE 

/etc/pcnfsd.conf 

SEEALSO 

lpr(l), lprm(l), lpc(8), lpq(l) 

25 Junel995 



plipconfig 

piipconfig— Fine-tune PLIP device parameters. 
SYNOPSIS 

plipconfig i n t e r f a c e 

plipconfig interface [nibble NN] [trigger NN] [unit NN] 



DESCRIPTION 

plipconfig isused to improvePLIP performance Py changing the default timing parameters used PythePLIP protocol. 
Resultsaredependent on the parai lei port hardware, caPle, and the CPU speed of each machineon each end of the PLIP 
link. 

If the single nterf a c e argument isgiven, plipconfig displays the status of the given interface only. Otherwise, ittriesto set 
theoptions. 

OPTIONS 

nibbie nn Sets the ni PPIe wait value i n microseconds. D efault is 3000. 

trigger nn Sets the trigger wait value in microseconds. D efault is 500. 

unit nn Sets the number of units of delay. D efault is 1. 

In somecases, PLIP speed can Peimproved Py lowering the default values. Valuesthat aretoo low might cause excess use of 
CPU, poor interrupt responsetimeresulting in serial ports drappi ngcharacters, or in dropping PLIP packets. Changing the 
plipMTU can al so affect PLIP speed. 

SEEALSO 

ifconfig(8) 

BUGS 

N oneso far. 

AUTHOR 

John Paul M OrriSOn (jmorriso@bogomips.ee. ubc.ca, ve7jpm@ve7jpm.ampr.org) 

1 July 1994 
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ping 

ping— Send IC M P echo_request packetsto network hosts. 
SYNOPSIS 

/etc/ping [ -r ][-v ] host [ packetsize ] [ c o u n t ] 

D ESC RIPTIO N 

T he D ARPA Internet isa largeand complex aggregation of network hardware, connected together by gateways. Trackinga 
si ngle-poi nt hardwareor software failurecan often bedifficult. Ping utilizesthe I C M P protocol's mandatory echo_request 
datagram to elicit an ICM P echo_response from a host or gateway. echo_request datagrams("pings") havean IP and ICM P 
header, followed by a struct timevai and then an arbitrary numberof "pad" bytesused to fili outthepacket. D efault 
datagram length ÌS64 bytes, but thismay bechanged usingthecommand-lineoption. Other opti ons are 

-r Bypass the normal routingtablesand send directly to a hoston an attached network. If 

the host isnoton a directly attached network, an errori sreturned. Thisoption can be 
used to ping a locai host through an interface that hasno routethrough it(for example, 
after the interface wasdropped by routed(8C)). 

-v Verbose output. ICM P packets other than echojesponse that are received are I i sted . 

When using ping for fault isolation, it should first berun on the locai host to verify that the locai network interface isup and 
running. Then, hosts and gateways fu rther away should bepinged. Pingsendsone datagram per second and printsoneline 
of output forevery echo_response returned. N o output isproduced if thereisno response If an optional count isgiven, only 
that numberof requestsissent. Round-trip times and packet-loss statistics are computed. When ali responses have been 
received or the program times out (with a count specified), or if the program is termi nated with a sigint, a brief summary is 
di splay ed. 

Thisprogram isintended forusein network testi ng, measurement, and management. 1 1 should beused primarilyformanual 
fault isolation. Becauseof theload it could impose on the network, it isunwiseto use ping during normal operationsor from 
automated scripts. 

AUTHOR 

M ikeM uuss 

SEEALSO 

netstat(l), ifconfig(8) 

19 September 1988 

portmap 

portmap— DARPA portto RPC program number mapper. 
SYNOPSIS 

portmap [-d] 

DESCRIPTION 

portmap isaserver that convertsRPC program numbersinto DARPA protocol portnumbers. It must be running in orderto 
makeRPC calls. 



When an RPC server isstarted, it tei Is portmap what port number it islisteningto and what RPC program numbers it is 
prepared to serve. W hen aclientwantsto makean RPC cali to a given program number, it first contacts portmap on the 
server machineto determi ne the port number where RPC packets should besent. 



powerd 



portmap must bestarted beforeany RPC serversareinvoked. 

Usually, portmap forksand dissoci ates itself from the terminal likeany other daemon. Portmap then logserrorsusing 
syslog(3). 

Option available 

-d (debug) prevents portmap from runningas a daemon and causeserrorsand debugging information to beprinted to the 
standard error output. 

SEEALSO 

inetd.conf(5), rpcinfo(8), inetd(8) 

BUGS 

If portmap crashes, ali servers must be restarted. 
HI STORY 

T he portmap command appeared in BSD 4.3. 

BSD 4.3, 16 March 1991 

powerd 

powerd— M onitor a serial lineconnected to a U PS. 
SYNOPSIS 

/etc/powerd seri al -devi ce 

D ESC RIPTIO N 

powerd is a daemon processthat sitsin the background and monitors the state of theDCD I i ne of the serial device. It is 
meantthatthis line isconnected to alJ PS (U ni nterruptible Power Supply) so that it knows about the state of theU PS. As 
soon as powerd senses that the power i sfai li ng (it sees that DCD goes low) it notifies imt{8) and init executesthepowerwait 
and powerfaii entries. If powerd senses that the power hasbeen restored, it notifies init again and init executesthe 
powerokwait entries. 

ARGUMENTS 

seri ai ■ devi ce Some serial portthat isnot beingused by some other device and does not 

sharean interrupt with any other serial port. 

DIAGNOSTICS 

powerd regularly checks the D SR lineto seeif it'shigh. DSR should be d i recti y con nected to DTR and powerd keepsthat line 
high, so if DSR islow, something iswrongwith the connection, powerd notifies you about thisfact every two minutes. W hen 
it sees that the connection is restored, itwill sayso. 

IMPLEM ENTATION 

It's pretty si mple to connect your U PS to the Linux machine. T he steps are easy: 

1. M akesureyou havean U PS with a si mple relais output: it should closeitsconnections(make) if the power isgone, and 
it should open its connections (break) if the power is good. 

2. Buy a serial plug. Connect the DTR lineto the DSR I i ne di rectly. Connect the DTR line and theDCD li ne with a 10 
kilo ohm resistor. Connect the relais-output of theU PS to GROU N D and theDCD line. If you don't know whatpins 
DSR, DTR, DCD and GROU N D are, you can alwaysask at thestorewhereyou bought the plug. 

3. You'reall set. 
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BUGS 

W eli, it'snot a real bug but powerd should beableto do a broadcast or something on the Ethernet in case more Li nux-boxes 
areconnected to thesameU PS and only oneof them isconnected to the U PS status line. 

SEEALSO 

shutdown(8), init(8), inittab(5) 

AUTHOR 

M iquel van Smoorenburg (miquelsedrinkel.nl.mugnet.org) 

14 February 1994 



pppd— Point-to-Point Protocol daemon. 
SYNOPSIS 

pppd [ 1 1 y n a me ] [s p e e d ][opti ons ] 

D ESC RIFTIO N 

The Point-to-Point Protocol (PPP) provides a method fortransmitting datagrams over serial poi nt-to-point links. PPP is 
composed of threeparts: a method forencapsulating datagrams over serial links, an extensible Link Control Protocol (LCP), 
and afamily of Network Control Protocols (N CP) for estabi ishing and confi guring different network-layer protocols. 

Theencapsulation schemeisprovided by driver code in the kernel, pppd provides the basic LCP, authentication support, and 
an NCP for establishing and configuri ng the Internet Protocol (IP) (called the IP Control Protocol, IPCP). 



FREQ U EN TLY U SED 0 PTIO N S 

1 1 y _ n a me 
s p e e d 

asyncmap map 



auth 

connect p 
crtscts 

defaultroute 



C ommunicate over the named device. The stri ng nevi isprepended if necessary. If no 
device nameisgiven, or if the nameof the controlli ng terminal isgiven, pppd usesthe 
controlli ng terminal and doesnotfork to put itself in the background. 
Setthebaud rate to s p e e d (adecimai number). On systemssuch as4.4BSD and 
N etBSD, any speed can bespecified. Other systems (such as SunOS) allow only a 
limited set of speeds. 

Set theasync character map to map. T hi s map describeswhich control characterscannot 
besuccessfully received over the serial line pppd asksthepeerto send thesecharactersas 
a 2-byte escape sequence. T he argument is a 32- bit hex number with each bit represent- 
ing a character to escape. Bit 0 (00000001 ) represents the character 0x00; bit 31 (80000000) 
represents the character 0x1 f or ". If multiple asyncmap optionsaregiven, thevaluesare 
oRed together. If no asyncmap option isgiven, no async character map is negotiated for 
the receive direction; thepeer should then escape ali control characters. 
Requirethepeer to authenti cate itself before allowing network packetsto besent or 
received. 

Usetheexecutableor shell command specified by p tosetup theserial line. This script 
typically usesthechat(8) program to dial the modem and start the remote PPP session. 
Use hardware fi ow control (that is, RTS/CTS) to control theflow of data on theserial 
port. If neither the crtscts northe -crtscts option isgiven, the hardware flow control 
setting for theserial port isleftunchanged. 

Adda default route to the system routi ng tables, usi ng the peer as the gateway, when 
IPCP negotiation issuccessfully compieteci. Thisentry isremoved when the PPP 
connection isbroken. 



pppd 
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disconnect p 



escape xx ,yy , 



file 
lock 



mtu n 



netmask n 



passive 



silent 



Run theexecutableor shell command specified by p after pppd hasterminated the link. 
Thisscri pt could, for example, issuecommandsto the modem to cause itto hangup if 
hardwaremodem control signals were not available. 

Specifiesthat certain charactersshould beescaped on transmission (regardlessof whether 
thepeer requeststhem to beescaped with itsasync control character map). The 
charactersto beescaped are specified asa list of hex numbersseparated by commas. 
N otethat almost any character can be specified for theescape option, unii ke the 
asyncmap option, which only allows control charactersto be specified. Thecharacters 
that cannot beescaped are those with hex values 0x20 - 0x3f oroxse. 
Read optionsfrom filef (the format isdescribed later). 

Specifiesthat pppd should create a U U C P-style lock fi le for the serial device to ensure 
exclusi ve access to the device. 

Set the M RU (M aximum ReceiveU nit) valueto n for negotiation. pppd asksthepeerto 
send packetsof no morethan n bytes. The minimum M RU value is 128. The default 
M RU value is 1500. A value of 296 isrecommended for slow links (40 bytes for TCP/IP 
header plus 256 bytes of data). 

Set the MTU (M aximum Transmit U nit) valueto n. Unless thepeer requestsa smaller 
value viaM RU negotiation, pppd requests that the kernel networking code send data 
packetsof no morethan n bytes through thePPP network interface 
Set the interface netmask to n, a 32-bit netmask in decimai dot notation (such as 
255.255.255.0). If thisoption isgiven, the value specified isoRed with thedefault 
netmask. The default netmask ischosen based on thenegotiated remotelP address; it is 
the appropriate network mask for the class of the remote IP address oRed with the 
netmasksfor any non-point-to-point network interfaces in the system that areon the 
same network. 

E nables the passive option in theLCP. With thisoption, pppd attemptsto initiatea 
connection; if no reply is recéved from thepeer, pppd then waits passively for a valid 
LC P packet from the peer (i nstead of exiting as it does without this option). 
With thisoption, pppd does not transmit LCP packetsto initiatea connection until a 
valid LCP packet is recéved from thepeer (as for the passive option with ancient 
versi onsof pppd). 



0PTI0NS 



locai IP addr ess :r e mot e IP address 



-ali 



Set the locai and/or remote interface IP addresses. Eitheronemaybe 
omitted. The IP addresses can be specified with a host nameor in decimai 
dot notation (such 35150.234. 56. 78). Thedefault locai addressisthe 
(first) IP address of the system (unless the noipdefauit option isgiven). 
The remote address isobtained from thepeer if not specified in any 
option. Thus, in simplecases, thisoption isnot required. If alocal and/or 
remotelP address i s specified with thisoption, pppd does not accept a 
different value from thepeer in the I PCP negotiation, unless the 
ipcp-accept-iocai and/or ipcp-accept-remote optionsare given. 
D isable Address/C ontrol compression negotiation (use default, address/ 
control field compression disabled). 

Don't request or allow negotiation of any optionsfor LCP and I PCP (use 
default vai ues). 

D isable asyncmap negotiation (use the default asyncmap; that is, escape ali 
control characters). 

Same as asyncmap n. 
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bsdcomp nr ,nt 



-bsdcomp 

+chap 

-chap 

chap-interval n 
chap-max-challenge n 

chap-restart n 

-crtscts 

■d 

debug 



-def aultroute 

-detach 
dns-addr n 

domain d 

-ip 

+ip-protocol 
-ip-protocol 

+ipx-protocol 



Request that thepeer compress packets that it sends, using the 
BSD -Compress scherme, with a maximum code sizeof n r bitsand agreeto 
compress packets sentto the peerwith a maximum code sizeof nt bits. If 
nt isnot specified, it defaultsto thevaluegiven fornr . Values in therange 
9to 15 maybeused fornr and nt; larger values givebettercompression 
but consume more kernel memoryforcompression dictionaries. 
Alternative^, a valueofe fornr or nt disablescompression in the 
corresponding direction. 

D isables compression; pppd does not request or agreeto compress packets 
usi ng the BSD -C om press scheme. 

Require the peer to autenticate itself using C H AP (C ryptographic 

H andshakeAuthentication Protocol) authentication. 

Don't agreeto authenticate using CHAP. 

If thisoption isgiven, pppd rechallenges the peer every n seconda 

Set the maximum number of CHAP challengetransmissionsto u (default 

ÌS10). 

Set theC H AP restart i nterval ( retran smission timeout for challenges) to n 
seconds (default i s 3). 

D isabl e hardware fi ow control (RTS/CTS) on the serial port. If neither 
thecrtscts northe -crtscts option isgiven, the hardware fi ow control 
setting for theserial port isleftunchanged. 
Increase debugging level (sameas the debug option). 
Increase debugging level (sameas -d). If thisoption isgiven, pppd logsthe 
contents of ali control packets sent or received in a readableform. The 
packets are logged through sysiog with faci I i ty daemon and level debug. 
Thisinformation can bedirected to a file by setting up /etc/sysiog.cont 
appropri ately (see sysiog. conf(5)). 

D isablethedefauitroute option. The system administratorwhowantsto 
prevent usersfrom creati ng default routeswith pppd can do so by piaci ng 
thisoption in the /etc/ppp/options file 

Don't fork to becomea background process(otherwise, pppd will do so if 
aserial device otherthan its controlli ng terminal is specified). 
Thisoption setsthelP addressor addressesfortheD omain N ame Server. 
It isused by M icrosoft Windows clients. Theprimary D N S addressis 
specified by the first instanceof the dns-addr option. The secondary is 
specified by thesecond instance. 

Append thedomain named tothelocal hostnamefor authentication 

purposes. Forexample, if gethost-nameo returnsthenameporsche, but 

thefully qualified domain nameisporsche.Quotron.coM, you use the 

domain option to set thedomain nameto Quotron.coM. 

DisablelP address negotiation. If thisoption isused, theremotelP 

addressmust be specified with an option on thecommand li ne or in an 

optionsfile 

EnablethelPCP and IP protocols. Thisis the default condition. This 

option isonly needed if thedefault setting is -ip-protocoi. 

D isablethelPCP and IP protocols. This should only beused if you know 

you are using a client that only understands IPX and you don't wantto 

confuse theclient with thelPCP protocol. 

EnablethelPXCP and IPX protocols. T his is the default condition if 

your kernel supports IPX. Thisoption isonly needed if thedefault setting 

is -ipx-protocoi. If your kernel does not support IPX, thisoption has no 

effect. 
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-ipx-protocol 

ipcp-accept-local 
ipcp-accept-remote 
ipcp-max-configure n 
ipcp-max-failure n 
ipcp-max-terminate n 
ipcp-restart n 
ipparam stri n g 

ipx -network n 



ipx-node n :m 



ipx-router-name stri n g 
ipx-routing n 

ipxcp-accept-local 

ipxcp-accept- network 

ipxcp-accept -remote 
ipxcp-max-configure n 



D isablethe IPXC P and IPX protocols. T his should only beused ifyou 

know you are using a client that only understandsIP and you don't want 

to confuse theclientwith thelPXCP protocol. 

Witti thisoption, pppd accepts the peer's idea of a locai IP address, even if 

thelocal IP address wasspecified in an option. 

With thisoption, pppd accepts the peer's idea of its (remote) IP address, 

even if the remote I P address wasspecified in an option. 

Set the maximum number of IPC P confi gure-request transmissions to n 

(default is 10). 

Setthemaximum number of IPCP configure-N AKsreturned before 
starti ng to send confi gure-Rejectsinstead to n (default is 1 0). 
Set the maximum number of IPC P terminate- request transmissions to n 
(default is 3). 

Set the I PC P restart i nterval (retransmission timeout) to n seconds 
(default is 3). 

Providesan extra parameter to theip-up and ip-down scripts. If this 
option isgiven, thestri ng supplied isgiven asthesixth parameter to 
those scripts. 

Set the IPX network number in thelPXCP configure request f rame to n. 
There isno valid default. If thisoption is not specifi ed, the network 
number is obtained from the peer. If the peer does not have the network 
number, the IPX protocol isnot started. Thisisa hexadecimal number 
and isentered without any leadingsequencesuch ascx. It isrelated to the 

ipxcp-accept-network Option. 

Set the I PX nodenumbers. Thetwo nodenumbersareseparated from 
each otherwith acolon character. The first numbern isthe locai node 
number. The second number m isthe peer's node number. Each node 
number is a hexadecimal number to themaximum of ten significant 
digits. The nodenumbers on theipx-network must beunique. There is 
no valid default. If thisoption isnot specified, the node number is 
obtained from the peer. Thisoption isa related to theipxcp-accept-iocai 

and ipxcp-accept-remote Options. 

Set the name of the router. This isa stri ng and issent to the peer as 
information data. 

Set therouting protocol to bereceived by thisoption. M orethan one 
instanceof ipx-routing may be specified. Thenoneoption (0) may be 
specified astheonly instanceof ipx-routing. Thevaluesare0 for none, 2 
for RIP/SAP, and 4 for N LSP. 

Accept the peer's NAK for the node number specified in theipx-node 
option. If a node number wasspecified and it is nonzero, the default isto 
insist that thevalue beused. Ifyou include thisoption, you permitthe 
peer to override the entry of the node number. 
Accept the peer's NAK for the network number specified in theipx- 
network option. If a network number was specified and it is nonzero, the 
default isto insist that thevalue beused. Ifyou includethisoption, you 
permit the peer to override the entry of the node number. 
U se the peer's network number specified in the configure request frame. 
If a node number was specified for the peer and thisoption was not 
specified, the peer isforced to use thevalue that you specified. 
Set the maximum number of IPXC P configure request frames that the 
system sendsto n. The default is 10. 
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ipxcp-max-failure n 
ipxcp-max-terminate n 

kdebug n 

lcp-echo-failure n 



lcp-echo-interval n 



lcp-max-configure n 
lcp-max-f ailure n 
lcp-max-terminate n 
lcp-restart n 
locai 

login 
modem 



name n 
noipdefault 



Set the maximum number of IPXCP NAK frames that the locai system 
sendsbeforeit re; ects the options. The default vai ue ÌS3. 
Set the maximum number of I PXC P termi nate request frames before the 
locai system considers that the peer isnot listeningto them. The default 
value is 3. 

E nable debugging code in the kernel-level PPP driver. The argumentn is 
a number that isthesum of the followi ng values: 1 to enable general 
debug messages, 2to request that the contents of received packets be 
printed, and 4to request that thecontentsof transmitted packets be 
printed. 

If this option isgiven, pppd presumes the peer is dead if n LCP echo- 
requestsaresentwithout recavi ng a valid LCP echo-reply. Ifthis 
happens, pppd terminates the connection. Useof thisoption requiresa 
nonzero value fortheicp-ecno-intervai parameter. Thisoption can be 
used to enable pppd to terminate after the physical connection hasbeen 
broken (for example, themodem hashung up) in situationswhereno 
hardwaremodem control lines are avai lable. 
If thisoption isgiven, pppdsendsan LCP echo-request f rame to the peer 
every n seconds. U nder Linux, the echo-request issentwhen no packets 
are received from the peer for n seconds. Usuai ly, the peer should respond 
to the echo-request by sendingan echo-reply. Thisoption can beused 
with the icp-echo-faiiure option to detect that the peer isno longer 
connected. 

Set the maximum number of LCP configure-requesttransmissionston 
(default is 10). 

Set the maximum number of LCP configure-NAKsreturned before 
starti ng to send confi gure-Rej ects instead to n (default is 10). 
Set the maximum number of LC P terminate-request transmissionsto n 
(default is 3). 

Set the LC P restart interval (retransmission timeout) to n seconds (default 
is 3). 

Don't use the modem control lines. W ith thisoption, pppd ignoresthe 
state of the CD (Carrier Detect) signal from themodem and doesnot 
change the state of the DTR (DataTerminal Ready) signal. 
Use the system password database for autenticati ng the peer using PAP, 
and record the user in the system wtmp file. 
Use the modem control lines. Thisoption isthe default. With this 
option, pppd waits for the C D (C arrier D etect) signal from the modem to 
beasserted when openingtheserial device(unless a connect script is 
specified), and it drops the DTR (DataTerminal Ready) signal bri ef ly 
when theconnection isterminated and before executing the connect 
script. On Ultrix, thisoption implies hardware flow control, as for the 
crtscts option. 

Disable magic number negotiation. With thisoption, pppd cannot detect 
a looped-back line. 

D isableM RU (M aximumReceiveU nit) negotiation. With thisoption, 
pppd uses the default M RU value of 1500 bytes. 
Set the name of the locai system for aumenti cation purposes to n . 
Disables the default behavior when no locai IP address is specified, which 
isto determine (if possible) the locai IP address from thehostname. With 
thisoption, the peer must supply the locai IP address duri ng I PCP 




negoti ation (unless it specified explicitly on thecommand line or in an 
optionsfile). 

Sameas the passive option. 
Requirethepeerto authenti cate itself using PAP. 
Don't agreeto authenti cate using PAP. 

Indicatesthat ali secrets in the/etc/ppp/pap-secrets file, which areused 
for checki ng the i denti ty of the peer, are encrypted, and thus pppd should 
not accept a password (beforeencryption) that i s identi cai to the secret 
from the /etc/ppp/pap-secrets file. 

Set the maximum number of PAP authenticate-request transmissions to n 
(default is 10). 

SetthePAP restart interval ( retran smission timeout) to n seconds (default 
is 3). 

Set the maximum ti me that pppd waitsfor the peer to authenti cate itself 
with PAP to n seconds(a meansno limit). 

Disable protocol field compression negotiation (use default, protocol field 
compression disabled). 

Do not exit after a connection is termi nated; instead, try to reopen the 
connection. 

Atterri pt to request that the peer send the locai system frames, which have 

been compressed by thePredictor-1 compression. The compression 

protocolsmust beloaded orthisoption isignored. 

Do not accept Predictor-1 compression, even if the peer wantsto send 

thistypeof compression and support hasbeen defined in the kernel. 

Add an entry to thissystem'sARP (Address Resolution Protocol) table 

with the IP address of the peer and the Ethernet address of this system. 

D i sable the proxyarp opti on. T he system admi nistrator who wants to 

prevent usersfrom creating proxy ARP entri es with pppd can do so by 

piaci ngthisoption in the /etc/ppp/options file. 

Set theassumed nameof the remote system for authenti cation purposes 

tO n. 

Agreeto authenti cateusing PAP (Password Authentication Protocol) if 
requested by the peer and use the data in fi le p for the user and password 
to send to the peer. The fi le contai ns the remote username, followed by a 
newline, followed by the remote password, followed by anewline This 
option isobsolescent. 

Enforcetheuseof the hostnameas the nameof thelocal system for 
authentication purposes (overrides the name option). 
Set the username to use for authenticating this machine with the peer 
using PAP to u. 

D isable negotiation of Van J acobson-styleTC P/IP header compression 
(use default, no compression). 

D isable the connection-ID compression option in Van Jacobson style 
TCP/IP header compression. With this option, pppd doesnot omit the 
connection-ID bytefromVanJacobsoncompressedTCP/IP headersor 
ask the peer to do so. 

Sets the number of connection slotsto beused by the Van Jacobson 
TCP/IP header compression and decompression code to n, which must be 
between 2 and 16 (inclusive). 
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xonxoff U se software fi ow control (XON/XOFF) to control theflowof dataon 

theserial port. Thisoption isonly implemented on Linux systemsat 
present. 

OPTIONS FILES 

Optionscan betaken from filesaswell asthecommand line, pppd readsoptionsfrom thefiles /etc/ppp/options and ~/.ppprc 
beforelookingatthecommand line. An optionsfileisparsed into aseri esof words, del i m i ted by whitespace. Whitespacecan 
beincluded in a word by enclosing the word in quotes("). A backslash (\) quotesthefollowingcharacter. A hash (#) startsa 
comment, which conti nuesuntil theend of theline. 

AUTH ENTICATION 

pppd prò vi des system administratorswith sufficient access control so that PPP access to a server machinecan beprovided to 
legiti mate users without fear of compromisi ng the security of the server or the network it'son. In part, thisis provi ded by the 
/etc/ppp/options file, where the administrator can place opti onsto requireauthentication whenever pppd isrun, and in part 
by thePAP and CH AP secretsfiles, where the administrator can restrict the set of IP addressesthat individuai users can use. 

The default behavior of pppd isto agreeto authenticateif requested and to not requireauthentication from thepeer. 
H owever, pppd doesnot agreeto authenticate itself with a parti cular protocol if it hasno secretsthat can beused to do so. 

Authentication isbased on secrets, which areselected from secretsfiles(/etc/ppp/pap-secrets for PAP, 
/etc/ppp/chap-secrets forCHAP). Both secrets fi les have the same format, and both can store secrets for several combina- 
ti onsof server (authenticating peer) and eli ent (peer bei ngauth enti cated). N otethat pppd can be both a server and client and 
that different protocolscan beused in thetwo di recti onsif desired. 

A secrets fi le is parsed into words as for an optionsfile. A secret isspecified by a li ne contai ni ngat least three words, in the 
order client name, server name, and secret. Any following words on thesamelinearetaken to bea list of acceptablelP 
addresses for that client. If there are only three words on theline, it isassumed that any IP address isokay; to disallow ali IP 
addresses, use -. If the secret startswith an e, what follows isassumed to be the name of a file from which to read the secret. 
A * as the client or server name matches any name. When selecting a secret, pppd takesthebest match— that is, the match 
with thefewest wildeards. 

A secrets fi le contai ns both secrets for use i n authenticating otherhosts and secrets that you useforauthenticatingyourself to 
others. W hi eh secret to useischosen based on thenamesof the host (the locai name) and itspeer (the remote name). The 
locai name is set as follows: 

If the usehostname option isgiven, Thelocal name is the hostnameof this machine (with thedomain 

appended, ifgiven). 

If the name option isgiven Usetheargument of the first name option seen. 

If thelocal IP address isspecified with a Use that name. Otherwise, use the hostnameof thismachine(with the 

hostname domain appended, ifgiven). 

When authenticating yourself usi ng PAP, there isalso a username, which is the locai nameby default, but can be set with the 
user option or the +ua option. 

T h e rem o te n am e i s set as f o 1 1 ows: 

If the remotename option isgiven Usetheargumentof thelast remote-name option seen. 

If the remote IP address isspecified with a Use that host name. Otherwise, the remote name isthe nuli 

hostname stri ng " " . 

Secrets areselected from thePAP secrets fi le as follows: 

■ For authenticating thepeer, look for a secret with client =usernamespecified in thePAP authenticate-request and 
server = locai name. 

■ For authenticating yourself to thepeer, look for a secret with client =your username and server = remote name. 




When authenticating the peer with PAP, a secret of "■ matchesany password supplied bythepeer. If the password doesn't 
match the secret, the password isencrypted usingcrypt( ) and checked against the secret again; thussecretsfor authenticat- 
ing the peer can bestored in encrypted form. If thepapcrypt option isgiven, the first (unencrypted) compari son isomitted 
for better security. 

If thelogin option wasspecified, theusernameand password arealso checked against the system password database. T hus, 
the system administrator can set up thepap-secrets fileto allow PPP access onlyto certain usersand to restrict the set of IP 
addressesthat each user can use. Typically, when using thelogin option, the secret in /etc/ppp/pap- secrets is ■■ to avoid the 
need to have the same secret in two places. 

Secrets are selected from the C H AP secrets file as follows: 

■ For authenticating the peer, look for a secret with client = name specified in theCH AP-Responsemessageand server 
= locai name 

■ For authenticating yourself to the peer, look for a secret with client = locai name and server = name specified in the 
C H AP-C hallenge message. 

Authentication must be satisfactorily compieteci beforelPCP (or any other N etwork Control Protocol) can bestarted. If 
autenticati on fails, pppd termi nates the link (by closingLCP). If IPCP negotiatesan unacceptablelP address for the remote 
host, IPCP isclosed. IP packetscan only besent or received when IPCP isopen. 

In somecases, it is desi rableto allow some h osts th at can 'tauth enti catethem sei vesto connectand useoneof a restricted set 
of IP addresses, even when the locai host general ly requires authentication. If the peer refusesto authenticateitself when 
requested, pppd takesthatasequivalentto authenticating with PAP using the empty string for theusernameand password. 
Thus, by adding a lineto thepap-secrets file, which specifies the empty string for the client and password, it is possi bleto 
allow restricted access to hoststhat refuse to autenticate themselves. 

ROUTING 

When IPCP negotiation iscompleted successfully, pppd informsthe kernel of thelocal and remotelP addressesforthePPP 
interface. T his is sufficient to create a host routeto the remote end of the link, which enablesthepeersto exchangelP 
packets. Communication with other machinesgenerally requires further modification to routing tables and/or ARP (Address 
Resolution Protocol) tables. In somecases, this is done automati cally through theactionsoftherouted orgated daemons, 
but in mostcases, somefurther intervention isrequired. 

Sometimesit is desi rableto add a default route through the remote host, asin the case of a machine whose only connection 
to the Internet is through the PPP interface The defauitroute option causespppd to create such a default route when IPCP 
comes up and delete it when the link is termi nated. 

In somecases, it is desi rableto useproxyARP— for example, on a server machineconnected to a LAN — to allow other hosts 
to communicatewith the remote host. Theproxyarp option causespppd to look for a network interface on the same subnet as 
the remote host (an interface supporti ng broadcast and ARP, which isup and not a point-to-point or loopback interface). If 
found, pppd createsa permanent, published ARP entry with the IP address of the remote host and the hardware address of 
the network interface found. 

EXAMPLES 

In thesimplest case, you can connect the serial portsof two machinesand issueacommand like 

pppd /dev/ttya 9600 passive 

to each machine, assumi ngthere isno getty running on the serial ports. If one machine has a getty running, you can use 
kermit or tip on the other machineto log in to thefirst machine and issuea command like 

pppd passive 

Then exitfrom the Communications program (makingsuretheconnection isn'tdropped) and issueacommand like 
pppd /dev/ttya 9600 
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The process of logging in to the other machine and starti ngpppd can beautomated by usingtheconnect option to run chat: 

pppd /dev/ttya 38400 connect 'chat login:" "username" 

"Password:" "pass-word" "% " "exec pppd passive" 1 

(N ote, however, that runningchat likethis leaves the password visiblein theparameter list of pppd and chat.) 

If your serial connection isany morecomplicated than a pieceof wire, you might need to arrangefor some control characters 
to beescaped. In particular, it isoften useful to escapeXON (^Q) and XO FF ('"S), usingasyncmap 30000. If thepath 
includes a telnet, you probably should escape"] aswell (asyncmap 20030000). If thepath includesan nogin, you need to use 
the escape ft option on the end that isrunningtherlogin eli ent becausemany rlogin implementationsarenot transparent; 
they remove the sequence(Oxff, Oxff, 0x73, 0x73, followed by any 8 bytes) from thestream. 

DIAGNOSTICS 

M essages are sent to thesysiog daemon usi ng the faci lity log_daemon. (Thiscan beoverridden by recompili ngpppd with the 
macro log_ppp defined as the desi red faci lity.) T 0 see the errar and debug messages, you need to edityour /etc/sysiog.cont 
fileto direct the messages to the desi red output device or file. 

The debug option causesthecontentsof ali control packetssent or received to belogged— that is, ali LCP, PAP, CH AP, or 
IPCP packets. Thiscan be useful if thePPP negotiation does not succeed. If debugging isenabled at compi le time, the debug 
0 pti 0 n al so causes oth er debuggi n g m essages to be I ogged . 

Debugging can also beenabled ordisabled bysendingasiGusRi to the pppd process. Thissignal actsasatoggle. 



FILES 

/vsr/run/pppn .pid (BSD or Linux) 
/etc/ppp/pppn .pid (others) 
/etc/ppp/ip-up 



/etc/ppp/ip-down 



/etc/ppp/ipx-up 



Process-ID for pppd process on PPP interface unitn. 

A program or script that isexecuted when the link isavailablefor sendingand 
recavi ng I P packets (that is, IPCP hascomeup). It isexecuted with the 

parameters i nt er f a c e- na me tty-device speed I ocal - I P-address remote- 1 P-address 

and with its standard input, output and errar streams redirected to /dev/nuii. 
T his program or script isexecuted with the samereal and effectiveuser-ID as 
pppd— thatis, atleast the effectiveuser-ID and possi bly the real user-ID will be 
root. T his isso that it can beused to manipulateroutes, run privi leged daemons 
(such assend-mail), and so on. Becareful that the contentsof the /etc/ppp/ip-up 
and /etc/ppp/ip-down scriptsdo not compromiseyoursystem'ssecurity. 
A program or script that isexecuted when the link isno longer available for 
sendingand receivingIP packets. T his script can beused for undoing the effeets 
of the /etc/ppp/ip-up script. It isinvoked with the same parameters as the ip-up 
script, and thesamesecurity considerations apply becauseit isexecuted with the 
sameeffectiveand real user-I Dsas pppd. 

A program or script that isexecuted when the link isavailablefor sendingand 
recavi ng I PX packets (that is, IPXCP hascomeup). It isexecuted with the 

parameters i nt er f a c e- na me tty-device speed network-number I ocal - 1 PX- node- 
address remote - 1 PX-node-address I ocal - I PX-routi ng-protocol remote-IPX- 
routi ng-protocol I ocal - I PX-router - na me r emot e- 1 PX- r out er ■ name pparampppd- 

pi d and with its standard input, output, and errar streams redirected to 
/dev/null. 

The I ocal ■ I PX- rout ng-protOCOl and remote-l PX- rojti ng- protocol field maybe 

oneof thefollowing: 
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none to indicate that there isno routing protocol, rip to indicate that RIP/SAP 
should beused. NLSPto indicate that Novell N LSP should beused. rip nlsp to 
indicate that both RIP/SAP and N LSP should beused. 
Thisprogram or script isexecuted with the samereal and ef recti ve user-ID as 
pppd— thatis, atleast the effecti ve user-ID and possi bly the real user-ID will be 
root. This isso that it can beused to manipulateroutes, run privileged daemons 
(such asripd), and so on. Becareful that the contentsof the /etc/ppp/ipx-up and 
/etc/ppp/ipx-down scriptsdo not compromiseyour system's security. 

/etc/ppp/ipx-down A program or script that isexecuted when the link isno longer availablefor 

sendingand recavi ng I PX packets. This script can beused forundoing the 
effectsof the /etc/ppp/ipx-up script. It is invoked with thesameparameters as 
theipx-up script, and the same security considerationsapply becauseit is 
executed with the same effecti ve and real user-I Dsas pppd. 

/etc/ppp/pap-secrets Usernames, passwords, and IP addressesfor PAP authentication. 

/etc/ppp/chap-secrets N ames, secrets, and IP addressesfor CHAP authentication. 

/etc/ppp/options System default optionsfor pppd, read beforeuser default optionsor command- 

lineoptions. 

"/.ppprc User default options, read beforecommand-lineoptions 

/etc/ppp/options. ttyname System default optionsfor the serial port bé ng used, read after command-line 

options. 

SEEALSO 

RFC 1144 Jacobson, V. Compressing TCP/IP headersfor low-speed serial links. February 

1990. 

RFC 1321 Rivest, R. The M D 5 M essage-D igest Algori thm. Aprii 1992. 

RFC 1332 McGregor, G. PPP Internet Protocol Control Protocol (IPCP). M ay 1992. 

RFC 1334 Lloyd, B.; Simpson, W.A. PPP authentication protocols. 1992 October. 

RFC 1548 Simpson, W .A. The Point-to-Point Protocol (PPP). December 1993. 

RFC 1549 Simpson, W. A. PPP in H DLC Framing. December 1993. 

NOTES 

T hefollowing signals havethe specified effectwhen sent to the pppd process: 

sigint, sigterm T hese si gnals cause pppd to termi nate the link (by closing LCP), resto re the seri al 

device settings, and exit. 

sighup Thissignal causes pppd to terminatethe li nk, restare the serial devi ce settings, and 

dose the serial device. If thepersist option hasbeen specified, pppd triesto 
reopen the serial devi ce and start another connection. Otherwise, pppd exits. 

sigusr2 Thissignal causes pppd to renegotiatecompression.Thiscan beuseful to re 

enable compressi on after it hasbeen disabled asa result of a fatai decompression 
error. W ith the BSD Compress scherme, fatai decompression errorsgenerally 
indicate a bug in oneor another implementati on. 

AUTHORS 

D rew Perkins, Brad Clements, Karl Fox, GregChristy, Brad Parker, and Paul M ackerras (pauiusics.anu.edu.au) 
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SYNOPSIS 

pppstats [ -v ] [ -r ][-c ] [ -i s ec s ] [uni t # ] 

DESCRIVO N 

pppstats prints PPP-related statistica 

The -v flag causes pppstats to display additional statistica auch asthenumber of packets tossed (that is, which theVJ TCP 
header decompression code rejected). 

The -r flag causes pppstats to display the overall packet compression rate. The rate valueisbetween 0 and 1, with 0 meaning 
that the data isincompressible. 

The -c flag isused to speci fy an alternate display mode that shows packet compression statistica thenumber of packets and 
bytesuncompressed (thatis, before compression or after decompression), compressed, and incompressi ble (packets that did 
notshrink on compression and weretransmitted uncompressed), and the recent compression rate. This rate reflects the 
recent performance of the compression code rather than theoverall rate the code compression wasenabled. 

The - iflag isused to speci fy the interval between printouts. The default is 5 seconda 

uni t# specifies which interface to use for gathering statistica 

2 Mayl995 

prunehistory 

prunemstory— Remove filenames from U senet hi story file. 
SYNOPSIS 

prunehistory [ -f f i I ename ] [ -p ] [i nput ] 

DESCRIPTION 

prunehistory modifies the history(5) text fi le to removea set of filenames from it. The filenames are removed by overwriting 
them with spacessothatthesizeand position of anyfollowing entri es do not change 

prunehistory reads the named input fi le or standard input if no file isgiven. The input istaken as a set of lines. Blank line 
and lines starti ng with a number sign (#) areignored. Ali other lines should consist of a M essage-ID followed by zero or more 
filenamea prunehistory usually compiai nsabout lines that do not follow this format. If the -p flag isused, then the program 
silently prints any invai id lineson its standard output. (Blank lines and comment lines are also passed through.) Thiscan be 
useful when prunehistory isused as a filter for other programssuch asreap. 

T he M essage-ID isused asthedbz(3) key to get an offset into the text file. If no filenames are menti oned on the input line, 
then ali filenames in the text are removed. If any filenames are mentioned, they areconverted into the history file notation. If 
they appear in the li ne for thespecified M essage-ID, they are removed. 

The default nameof the history file is /news/iib/history; to speci fy adifferent name, use the -f flag. 

Becauseinnd(8) only appendsto the text file, prunehistory does not need to haveany interaction with it. 

It isagood ideato delete purged entriesand rebuild thedbz database every so often by usi ng a script such asthefollowing: 

ctlinnd throttle "Rebuilding history database" 
ed /news/lib 
awk 'NF > 2 { 

printf "%s\t%s\t%s",$1,$2,$3; 
for (i = 4; i <= NF; i++) 
printf " %s", $i; 
print "\n"; 

}' <history >history.n 

if makehistory -r -f history. n ; then 
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mv history.n history 

rav history. n.pag history. pag 

mv history . n . dir history. dir 

else 

echo 'Problem rebuilding history; old file not replaced 
fi 

ctlinnd go "Rebuilding history database" 

N otethat this keeps no record of expired articles. 
HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
SEEALSO 

dbz(3), history(5), innd(8) 



quotacheck 

quotacheck— Scan a filesystem for disk usages. 



SYNOPSIS 

quotacheck [-g] [-u] [-v] -a 
quotacheck [-g] [-u] [-v] fi I e s y s ... 

D ESC RIPTIO N 

quotacheck performs a filesystem scan for usageof filesand directories, used by either user or group. The output is the quota 
fi le for the correspondi ng fi I esystem . By default, the names for these f i les are 

A user SCan quota. user 

A group SCan quota. group 

Theresultingfileconsistsof astruct dqbikforeach possiblelD up to the highest existing U ID orGID and contai ns the 
values for the disk file and block usage and possibly excesstimeforthesevalues. (For definitionsof struct dqbik, see 

linux/quota. h.) 

quotacheck should berun each ti me the system bootsand mounts non-vai id filesystems. Thisismost likely to happen after a 
system crash. 

Thespeed of the scan decreaseswith theamount of directories increasi ng. Thetimeneeded doubleswhen disk usage is 
doubled aswell. A 100M B parti ti on used for 94 percent isscanned in one minute; the same partiti on used for 50 percent is 
donein 25 seconds. 



0PTI0NS 



Thisway, the program will givesomeuseful information aboutwhat it isdoing, plus 
somefancy stuff. 

Thismeans debug. It will result in a lot of information thatcan beused in debugging 
the program. The output isvery verbose and the scan will not be fast. 
Thisflag tei Is the program to scan the disk and to count thefiles and directories used by 
acertain U ID . Thisis the default action. 

Thisflagforces the program to count the fi les and directories used by acertain GID . 



NOTE 



checkquota should only berun assuperuser. N on-privileged usersarepresumably not allowed to read ali the directories on 
thegiven filesystem. 
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SEEALSO 

quota(l), quotaotl(2), fstab(5), quotaon(8), quotaoff(8), edquota(8), repquota(8), fsck(8), efsck(8), e2fsck(8), xfsck(8) 

FILES 

quota. user- 
quota. group 
/etc/fstab 

AUTHOR 

Edvard Tuinder (v89223ifei.hhs.nl, etuinderWeliriuin.nl.inugnet.org), M arco van Wieringen (v8922730si.hhs.nl, 
mvwftncs . ni . mugnet . org). 

21 August 1993 



quotaon, quotaof f 

quotaon, quotaof f— Tum filesystem quotason and off. 
SYNOPSIS 

/usr/etc/quotaon [ -vug ] filesystem... 
/usr/etc/quotaon [ -avug ] 

/usr/etc/quotaoff [ -vug ] filesystem... 
/usr/etc/quotaoff [ -avug ] 

D ESC RIPTIO N 

quotaon announcesto the system that disk quotasshould beenabled on oneor more fi lesystems. The filesystem quota fi les 
must bepresent in theroot directory of thespecified filesystem and be named quota. user for user quota or quota. group for 
group quota. 

quotaof f announcesto the system that fi lesystems specified should haveany disk quotasturned off. 

OPTIONS 

quotaon 

-a Ali fi lesystems in /etc/fstab marked read-writewith quotaswill havethar quotas 

turned on. Thisisusually used at boot timeto enablequotas. 



-v D isplay a messageforeach filesystem where quotas are turned on. 

-u M anipulate user quotas. T his isthe default, 

-g M anipulate group quotas 

quotaoff 

-a Forceall filesystemsin /etc/fstab to havetheir quotas disabled. 

-v Di splay a messageforeach filesystem affected. 

-u M anipulate user quotas. T his isthe default. 

-g M anipulate group quotas 

FILES 

quota, user U ser quota file at thefilesystem root 

quota. group Group quota file at thefilesystem root 

/etc/fstab D efault filesystems 



SEEALSO 

quotactl(2), f stab(5) 

8Junel993 

rarp 

rarp— M ani pillate the system RARP table 
SYNOPSIS 

rarp [ -v] [ -t t y pe ] -a [host na me ] 

rarp [ -v] -d host name ... 

rarp [-v] [ -t type] -s hostname hwaddr 

D ESC RIPTIO N 

rarp mani pulates the kernel's RARP table in variousways. The primary options are clearing an addressmapping entry and 
manually setti ng up one For debugging purposes, the rarp program also allows a complete dump of the RARP table. 

OPTIONS 

-V 

-t type 



-a [host name ] 
-d host name 
-s host name hwaddr 

FILES 

/proc/net/rarp 

AUTHORS 

ROSS D . M arti n (martin@trcsun3.eas.asu.edu), Fred N . van Kempen (waltje@uwalt.nl.mugnet.org). 

Iljunel994 

rdev 

rdev— Query/set imageroot device, swap device, RAM disk size, or video mode. 
SYNOPSIS 

rdev [ -rsvh ] [ -o offset ] [ i ma g e [ value [ offset ]]] 
rdev [ -o offset ] [ i ma g e [ rootjevice [ offset ]]] 
swapdev [ -o offset ] [ i ma g e [ swap_device [ offset ]]] 
ramsize [ -o offset ] [ i ma g e [ size [ offset ]]] 
vidmode [ -o offset ] [ i ma g e [ mode [ offset ]]] 
rootflags [ -o offset ] [ i ma g e [ flags [ offset ]]] 



Teli the user what isgoing on by bei ng verbose. 

W hen setting or reading the RARP table, this optional parameter tei Is rarp which class 
of entri es it should check for. The default value of this parameter isetner (hardware 
code 0x01 for IEEE 802.3 10M bps Ethernet). Other values might include network 
technologiessuch asAX.25 (ax25). 

Shows the entri esof thespecified hosts. If thehost name parameter isnotused, ali entries 
are di splay ed. 

Rem ove the entri esof thespecified host. This can beused if theindicated host is 
brought down, for example 

Create an RARP addressmapping entry for host host name with hardware address setto 
hw_addr class, but for most classes, you can assume that the usuai presentati on can be 
used. For the Ethernet class, thisis6 bytesin hexadecimal, separated by colons. 
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DESCRIPTION 



With no arguments, rdev outputsan /etc/mtab lineforthecurrent root filesystem. With no arguments, swapdev, ramsize, 
vidmode, and rootfiags print usage inform ation. 

In a bootableimagefor the Linux kernel, there are several pairsof bytesthat specify the root device, the video mode, thesize 
of the RAM disk, and theswap device. These pairsof bytes, by default, begin at offset 504 (decimai) in the kernel image: 

498 Root flags 
(500 and 502 Reserved) 
504 RAM DiskSize 
506 VGA Mode 
508 Root Device 
(510 Boot Signature) 

rdev changes these values. 

Typical values for the image parameter, which isa bootable Linux kernel image, areasfollows: 

/vmlinux 

/vmlinux.test 

/vmunix 

/vmunix.test 

/dev/fd0 

/dev/fd1 

When using the rdev or swapdev commands, the root devi ce or swap device parameter areasfollows: 

/dev/hda[1 -8] 
/dev/hdb[1-8] 
/dev/sda[1 -8] 
/dev/sdb[1 -8] 

For the ramsize command, thesize parameter specifiesthesizeof the RAM disk in kilobytes. 

For the rootfiags command, the fi ags parameter contains extra information used when mounting root. Currently, theonly 
effect of these flags isto force the kernel to mount the root filesystem in read-only mode if fi ags is nonzero. 

Forthevidmode command, the mode parameter specifies the video mode: 

■3 Prompt 



-2 ExtendedVGA 
-1 N ormai VGA 



0 Asif 0 was pressed attheprompt 

1 As if 1 was pressed at the prompt 

2 Asif 2 was pressed attheprompt 
n Asif n was pressed attheprompt 



If thevalueis not speci fi ed, theimageisexamined to determi ne the current setti ngs. 



0PTI0NS 



-h 



-v 



- r 



-R 



s 



Causes rdev tO act like swapdev. 
Causes rdev tO act like ramsize. 
Causes rdev tO act like rootfiags 
C auses rdev tO act like vidmode. 

Provides help. 
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BUGS 

For historical reasons, therearetwo methodsfor specifying alternati ve valuesfor the offset. 

T he user interface is cu m berso me, non-intuitive, and should probably be rewritten from scratch, allowing multiple kernel 
image parametersto bechanged orexamined with a single command. 

If LI LO isused, rdev isno longer needed for setti ng the root device and the VGA mode because the parametersthat rdev 
modifiescan be set from the LI LO prompt during a boot. H owever, rdev is stili needed at thistimefor setti ng the RAM disk 
size. Usersareencouraged to find the LI LO documentati on for moreinformation and to use LI LO when booti ngtheir 
systems. 

AUTHORS 

Originally by Werner Al mesberger (aimesberianessie.es. id.etnz.cn). M odified by Peter M acDonald 

(pmacdona@sanjuan.UVic.CA). rootflags Support added by Stephen T weedie (sct@dcs . ed.ac .uk). 

Linux 0.99, 20 N ovember 1993 



renice 

renice— Alter priority of running processes. 
SYNOPSIS 

renice priority [[-p] pi rj ...] [[ -g] pgrp ...] [[-u] user ...] 

D ESC RIPTIO N 

renice alters the scheduli ng priority of one or more running processes. The following"who" parametersareinterpreted as 
processi Ds, processgroup IDs, or user names. reniceingaprocessgroup causesall processes in the processgroup to have 
their scheduli ng priority altered. reniceing a user causes ali processes owned by the user to have their scheduli ng priority 
altered. By default, the processes to beaffected are specified by their process IDs. 

0 ptions supported by renice: 

-g Forcewho parametersto beinterpreted as process group IDs. 

-u Forcethewho parametersto beinterpreted asusernames. 

-p Reset the who interpretation to be (the default) process IDs. 

Thefollowing examplechanges the priority of process I D S987 and 32 and ali processes owned by usersdaemon and root: 

renice +1 987 -u daemon root -p 32 

Usersother than thesuperuser can only alter the priority of processes they own and can only monotonically increase their 
"nicevalue" within therangeo to priojiax (20). (This prevents overriding admi n i strati ve fiats.) Thesuperuser can alter the 
priority of any process and set the priority to any valuein therangepRio_MiN (-20) to prio_max. Useful prioritiesare 20 (the 
affected processes run only when nothingelse in the system wantsto), 0 (the "base" scheduli ng priority), and anything 
n egati ve (to m ake th i n gs go very fast) . 

FILES 

/etc/passwd to map usernamesto user IDs 
SEEALSO 

getpriority(2), setpriority(2) 

BUGS 

Non-superuserscannot increase scheduli ng prioritiesof their own processes, even if they were the onesthat decreased the 
prioritiesin the first place. 
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HISTORY 

Therenicecommand appeared in BSD 4.0. 

BSD 4, 9Junel993 



repquota 

repquota— Summarizequotasfor a filesystem. 
SYNOPSIS 

/usr/etc/repquota [ -vug ] filesystem... 
/usr/etc/repquota [ -avug ] 

D ESC RIPTIO N 

repquota printsa summary of the disk usageand quotasfor the specified filesystems. For each user, thecurrent numberof 
filesand amount of space (in kilobytes) is printed, along with any quotas created with edquota(8). 

OPTIONS 

-a Report on ali fi lesystems indicateci in /etc/fstab to beread-writewith quotas. 

-v Report ali quotas even if thereisno usage. 

■g Report quotasfor groups. 

-u Report quotasfor users. Thisisthe default. 

0 nly thesuperuser can view quotas that are not their own. 
FILES 

quotas Q uota fi le at the filesystem root 

/etc/fstab D efault filesystems 

SEEALSO 

quota(l), quotactl(2), edquota(8), quotacheck(8), quotaon(8) 

8Junel993 

rexecd 

rexecd— Remote execution server. 
SYNOPSIS 

rexecd 

DESCRIPTION 

rexecd is the server for the rexec(3) routine. The server provides remote execution faci lities with autenticati on based on 
usernames and passwords. 

rexecd listensfor service requests at the port indicated in theexec servi ce speci fi cation; seeservices(5). When aservi ce 
request is received, the following protocol isinitiated: 

1. The server readscharactersfrom thesocket up to a nuli \« byte. The resultant stri ng isinterpreted asan ASCII number, 
base 10. 



rlogind 



FI 



2. If thenumber received in Step 1 is nonzero, it isinterpreted astheport number of asecondary stream to beused forthe 
stderr. A second connection isthen created to the specified port on the eli ent's machine. 

3. A null-terminated usernameof at most 16 charactersis retri eved on theinitial socket. 

4. A null-terminated, unencrypted password of at most 16 characters isretrieved on theinitial socket. 

5. A null-terminated command to bepassed to ashell isretrieved on theinitial socket. The length of thecommand is 
limited by the upper bound on the sizeof the system 's argument list. 

6. rexecd then validates the user asisdoneat login ti me and, if theauthentication wassuccessful, changesto theuser's 
home directory and establishes the user and group protectionsof the user. If anyof these steps fai I, theconnection is 
aborted with a diagnostic message return ed. 

7. A nuli byte isreturned on theinitial socket and thecommand lineispassed to thenormal login shell of the user. The 
shell inherits the network connectionsestablished by rexecd. 



Except for the last one listed, ali diagnostic messages are return ed on theinitial socket, after which any network connections 
areclosed. An errar is indicated by a leading byte with a valueof 1 (0 isreturned in Step 7 upon successful completi on of ali 
the steps priorto thecommand execution). 



DIAGNOSTICS 



Login incorrect. 
No remote directory 
Try again. 



<s h e I I n a me > : 



username too long 
password too long 
command too long 



Thenameislonger than 16 characters. 
The password islonger than 16 characters. 

Thecommand linepassed exceeds the sizeof theargument list (asconfigured into the 
system). 

N 0 password file entry for the username existed orthewrong password was supplì ed. 
Thecndir command to the home directory fai led. 
A fork by the server fai led. 

Theuser's login shell could not bestarted. This message isreturned on theconnection 
associ ated with the stderr and is not preceded by a flag byte. 




BUGS 



A faci I ity to allow ali data and password exchangesto beencrypted should bepresent. 



HI STORY 

The rexecd command appeared in BSD 4.2. 



BSD 4.2, 16 March 1991 



rlogind 



riogind— Remote login server. 



SYNOPSIS 



rlogind [-aln] 



DESCRIPTION 



riogind is the server for the riogin(l) program. T he server provides a remote login faci lity with authentication based on 
privi leged port numbersfrom trusted hosts. 
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0 ptions supported by riogind: 

-a Ask hostnamefor verification. 

-ì Prevent any authentication based on theuser's .rhosts fileunlesstheuser islogging in 

asthesuperuser. 
-n Disablekeep-alivemessages. 

nogind listens for servi ce requests at the port indicateci in the "login" servi ce speci fi cation; seeservìces(5). When a servi ce 
request is received, the following protocol isinitiated: 

1. The server checks the client'ssource port. If the port isnot in the range 512-1023, the server aborts the connection. 

2. The server checks the client'ssource address and requests the corresponding hostname(seegethostbyaddr(3), hosts(5), 
and named(8)). If the hostname cannot be determi ned, thedot-notation representati on of the host address isused. If the 
hostnameisin the same domain as the server (accordi ngto thelasttwo componentsof the domain name), or if the -a 
option isgiven, the addresses for the hostname are requested, verifying that the name and address correspond. N ormai 
authentication isbypassed if theaddress verification fails. 

Oncethesourceport and address h ave been checked, nogind proceedswith the authentication processdescribed in rsnd(8). 
It then allocatela pseudo terminal (seepty(4)) and mani pulates fi le descriptors so that the slave halfof the pseudo terminal 
becomesthestdin, stdout, and stderr for a login process. The login processisan instanceof theiogin(l) program, invoked 
with the - t option if authentication hassucceeded. If automati c authentication fails, the user isprompted to log in asif on a 
standard terminal line. 

Theparent of the login process mani pulates the master side of the pseudo terminal, operati ng asan intermediary between the 
login process and the cjient instanceof the riogin program. In normal operation, thepacket protocol described in pty(4) is 
invoked to provide S/Q typefacilitiesand propagate interrupt signalsto the remote programs. Thelogin process propagates 
the client termi nal'sbaud rate and terminal type, asfound in theenvironment variable, term; seeenviron(7). Thescreen or 
window sizeof the terminal is requested from the client, and window sizechangesfrom the client are propagated to the 
pseudo terminal. 

Tran sport- leve! keep-alivemessagesareenabled unlessthe -n option ispresent. The use of keep-alivemessages al lows sessi ons 
to betimed out if the client crashesor becomesunreachable. 

DIAGNOSTICS 

Ali initial diagnostic messagesareindicated by a leading byte with a valueof 1, after which any network connectionsare 
closed. If there are no errors before login is invoked, a nuli byte is returned asin indication of success. 

Try again. A fork by the server fai led. 

SEEALSO 

login(l), ruserok(3), rshd(8) 

BUGS 

The authentication procedure used hereassumestheintegrity of each client machine and theconnecting medium. This is 
insecurebut isuseful in an "open" environment. 

A faci I ity to allow ali data exchangesto beencrypted should bepresent. 

A more extensible protocol should beused. 

HI STORY 

The nogind command appeared in BSD 4.2. 

BSD 4.2, 16 March 1991 
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route 

route— Show/mani pulate the I P routi ng table. 
SYNOPSIS 



route [ -vn ] 

route [ -v ] add [ -net | -host ] XXXX [gw GGGG] [metric MHHH] [netmask NNNN ] 
[mss NNNN] [wìndow NNNN] [dev DDDD] 
route [ -v ] del XXXX 



DESCRIPTION 

route manipulatesthekemel'sIP routi ng table. Its primary use isto set up stati c routesto specific hostsor networksviaan 
interface after it hasbeen configured with theifconfig(8) program. This versi on of route isintended solely for usewith 
kernel versions 0.99pll4n and newer kernels. 

OPTIONS 

(none) P ri ntsout the kernel routing table, listing destination address, gateway, netmask for 

route ("Genmask"), flags (u =U p, h =H ost, g =Gateway, d =dynamic, m =M odified), 
Metric (currently not supported), Ref, use, and iface (which devi ce the route mapsto). 

-n Sameas previ ousbut shows numeri cai addressesinstead of tryingto determi ne symbolic 

host names. 

-v A flag for verbose (not actually used). 

dei xxxx D eletes the route associateci with the destination addressxxxx. 

add[-net j -host ] xxxx [gw gggg ] Adds a route to the I P address xxxx. T he route is a network route if the -net modifier is 

[metric MMMM ] [netmask NNNN] USed Or XXXX isfound in /etc/networks by the getnetbyname( ) library function and no 

[dev dddd] -host modifier isused. 

Thegw gggg argument meansthatany IP packets sent to thisaddresswill berouted 

through the specified gateway. N ote Thespecified gateway must be reachable first. This 

usually meansthat you haveto set up a stati c route to the gateway beforehand. 

The metric mmmm modifier is not yet implemented (and with the -v option will actually 

printawarning). 

The netmask nnnn modifier specifiesthe netmask of therouteto beadded. Thisonly 
makessensefor a network route and when the address xxxx actually makessensewith 
thespecified netmask. If no netmask isgiven, route guessesit instead, so for most 
normal setups, you won't need to speci fy a netmask. 

The mss nnnn modifier specifies theTC P mss for therouteto beadded. This is usually 
used only for fine optimization of routing setups. 

Thewindow nnnn modifier specifies theTC P window for therouteto beadded. This is 
typically only used on AX.25 networks and with driversunableto handleback-to-back 
frames— such asthe3c501 or D E 600. 

Thedev dddd modifier forces the route to beassociated with thespecified device because 
thekernd will otherwisetry to determinethedeviceon itsown (by checking already 
exi sting routes and device specif ications and where the route is added to). I n most 
normal networks, you won't need this. 

If dev dddd isthelast option on thecommand line, the word dev may beomitted 
because it's the default. Otherwise, the orderof the route modifiers (metric, netmask, gw, 
and dev) doesn't matter. 
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EXAMPLES 

route add -net 127. 0. 0.0 



route add -net 192.56.76.0 
netmask 255.255.255.0 dev eth0 

route add default gw mango-gw 



route add ipx4 sl0 route add 
192.57.66.0 netmask 255.255.255 
gw ipx4 



Addsthenormal loopback entry, using netmask 255.0.0.0 (ClassA net determined from 
the desti nation address) and associ ated with the io device(assumingthisdevicewas 
previ ously set up correctly with ifconf ig(8)). 

Addsa route to the network 1 92. 56. 76. % viaetno.TheClassC netmask modifier isnot 
really necessary here becausei92.* isaClassC IP address. The word dev can beomitted 
here 

Addsa default route (which will beused if no other route matches). Ali packets using 
thisroute will begatewayed through mango-gw. Thedevi ce that will actually beused for 
that route dependson howyou can reach mango-gw; the stati c route to mango-gw will have 
to beset up before. 

net Thiscommand sequenceadds the route to theipx4 host via the SLIP interface 

(assumi ng that ìpx4 is the SLIP host) and then addsthenet 192.57.66.0 to begatewayed 
through that host. 



FILES 



/proc/net/route 

/etc/networks 

/etc/hosts 

SEEALSO 

lfconflg(8) 

HI STORY 

route for Linux was ori ginally written by Fred N . van Kempen (waitje@uwait.ni.mugnet.org) and then modified byjohannes 
Stille and LinusTorvaldsfor pll5. Alan Coxadded themss and window optionsfor Linux 1.1.22. 

14 Junel994 



routed 

routed— N etwork routing daemon. 
SYNOPSIS 

routed [-d] [ -g] [-q] [-s] [-t] [logfile] 

DESCRIPTION 

routed isinvoked at boottimeto manage the network routi ng tabi es. The routing daemon usesa variant of the Xerox N S 
Routing Information Protocol in maintaining up-to-date kernel routing tabi e entri es. Itused ageneralized protocol capable 
of use with multi pi e address types but iscurrently used only for Internet routi ngwithin acluster of networks. 

In normal operation, routed listenson theudp(4) socketfortheroute(8) service(seeservices(5)) for routing information 
packets. If the host isan internetwork router, it periodically supplies copies of its routing tablesto any directly connected 
hostsand networks. 

When routed isstarted, it usesthesiocGiFcoNF iocti(2) to find those directly connected interfaces configured into the system 
and marked "up" (the software loopback interface isignored). If multiple interfaces are present, it isassumed that the host 
will forward packets between networks. routed then transmitsa request packet on each interface (using a broadcast packet if 
the interface supports it) and entersa loop, I isteni ng for request and response packets from other hosts. 



routed 1381 

W hen a request packet is received, routed formulate a reply based on the information maintained in its internai tables. The 
response packet generateci containsa list of known routes, each marked with a"hop count" metric (acount of 16, or greater, 
isconsidered "infinite"). The metric associ ated with each route return ed provides a metric relative to thesender. 

Response packets received by routed are used to update the routing tables if one of the followi ng condì ti ons is satisfied: 

No routing tabi e entry existsfor the desti nation network or host, and the metric indicates the desti nati on is'Yeachable" 
(thehop count isnot infinite). 

Thesourcehost of the packet isthesameastherouter in theexisting routing table entry. That is, updated information is 
bé ng received from thevery internetwork routerthrough which packets for the desti nation arebeing routed. 
Theexisting entry in the routing table hasnot been updated for sometime(defined to be90 seconds) and the route isat 
least as cost effective as the current route. 

Thenew route descri bes a shorter route to the desti nation than theonecurrently stored in the routing tables; the metric 
ofthenew route iscompared against the one stored in thetableto decidethis. 

When an update is appi i ed, routed recordsthechangein itsinternal tables and updates the kernel routing table. Thechange 
is reflected in the next response packet sent. 

In additi on to processing incoming packets, routed also peri odi cally checks the routing table entri es. If an entry hasnot been 
updated for threeminutes, the entry's metric is setto infinity and marked for deletion. D eletions are delayed an additi onal 
60 seconds to ensure the invalidation ispropagated throughout the locai Internet. 

Hostsactingas internetwork routers gratuitously supply their routing tablesevery 30 seconds to ali d i recti y con nected hosts 
and networks. The response is sent to the broadcast addresson nets capable of that function, to the destination addresson 
poi nt-to-point links, and to therouter'sown addresson other networks. The normal routing tables are bypassed when 
sending gratuitous responses. The reception of responseson each network isused to determi ne that the network and 
interface are functioning correctly. If no response is received on an interface, another route may bechosen to route around 
the interface, or the route may bedropped if no alternative isavailable. 

Opti ons supported by routed: 

-d Enableadditional debugging information to belogged, such asbad packets received. 

-g Thisflag isused on internetwork routers to offer a route to the "default" destination. 

This istypically used on agateway to the Internet oron a gateway that uses another 

routing protocol whose routes are not reported to other locai routers. 
-s Supplying this opti on forces routed to supply routing information whether it isacting as 

an internetwork router or not. This is the default if multiple network interfacesare 

presentorif apoint-to-pointlink isin use. 
-q Thisistheoppositeof the -s option. 

-t If the -t option isspecified, ali packets sent or received areprinted on the standard 

output. In addition, routed will not divorce itself from the controlling terminal so that 
interruptsfrom thekeyboard will kill theprocess. 

Any other argument supplied is interpreted asthenameof fi le in which routed'sactionsshould belogged. This log contains 
information about any changes to the routing tables and, if not traci ng ali packets, a history of recent messages sent and 
received that are rei ated to thechanged route. 

In addition to the faci I iti es descri bed previ ously, routed supports the noti on of "distant" passive and activegateways. W hen 
routed isstarted, it readsthefileto find gatewaysthat might not belocated usingonly information from thesioGiFcoNFiocti 
(2). G ateways speci fi ed i n this manner should be marked passi ve if they are not expected to exchange routing information, 
whereas gateways marked acti ve should bewilling to exchange routing information (that is, they should have a routed process 
running on the machine). Routes through passive gateways are instali ed in the kernel's routing tables once upon startup. 
Such routes are not included in any routing information transmitted. Activegateways are treated equally to network 
interfaces. Routing information isdistributed to the gateway, and if no routing information is received for a period of the 
time, theassociated route isdeleted. Gateways marked external are also passive but are not placed in the kernel routing table 
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nor are the/ included in routing updates. Thefunction of external entri es isto inforni routed that another routing process 
will instali such a routeand that alternate routesto that desti nation should not be instai led. Such entries are only required 
when both routers might learn of routesto thesamedestination. 

The /etc/gateways is compri sed of a seri es of lines, each in the following format: 

<net|host> namel gateway n a me 2 metrìc «al ne <passive | active j external> 

The net or host keyword indi cates i f the route isto a network or speci fic host. 

namei i s the name of the desti nation network or host. Thiscan bea sym boli c namelocated in or known to the name server if 
started after named(8) or an Internet addressspecified in "dot" notati on; seeinet(3). 

name2 isthe name or address of thegateway to which messages should beforwarded. 

vai ue isa metric indicati ng the hop countto the desti nation host or network. 

0 ne of the keywords passive, active, or externai i ndi cates if thegateway should betreated aspassi ve or active(asdescribed 
previ ously) or whether the gateway is external to the scope of the routed protocol. 

Internetwork routers that are di rectly attached to theARPAnet or M il net should use the Exteri or Gateway Protocol (EGP) to 
gather routing informati on rather than use a static routing tableof passive gateways. EGP is required in order to provide 
routesfor locai networksto therest of the Internet system. Sites needing assistancewith such configurations should contact 
the Computer Systems Research Group at Berkeley. 

FILES 

/etc/gateways for distant gateways 
SEEALSO 

udp(4), icmp(4), XNSrouted(8), htable(8) 

Internet Transport Protocols, XSIS 028112, Xerox System Integration Standard 
BUGS 

Thekernel's routing tablesmay not correspond to thoseof routed when redirectschangeoradd routes. routed should note 
any redirects received by readingthelCM P packets received viaarawsocket. 

routed should incorporate other routing protocols, such asXeroxNS, xNSrouted(8), and EGP . U si ng separate processes for 
each requiresconfiguration optionsto avoid redundant or competi ng routes. 

routed should li sten to intelligent interfaces, such asan IM P, to gather more informati on. It doesnotalwaysdetect 
unidirectional failuresin network interfaces (such aswhen the output si de fai Is). 

HISTORY 

The routed command appeared in BSD 4.2. 

BSD 4.2, 16 March 1991 

rpc.rusersd 

rpc.rusersd— Logged-in users server. 
SYNOPSIS 

/usr/libexec/ rpc . rusersd 

D ESC RIPTIO N 

rpc.rusersd isaserver that returnsinformation about users currently logged in to thesystem. 



rpci nfo 
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Thecurrently logged-in users arequeried usingtherusers(l) command. Therpc.rusersd daenon isusually invoked by 

inetd(8). 

rpc.rusersd USesan RPC protocol defined in /usr/ìnclude/rpcsvc. 

SEEALSO 

rusers(l), who(l), w(l), inetd(8) 

BSD 4.3, 7 Junel993 



rpc.rwalld 

rpc . rwaiid— W ri te messages to users currently logged i n to the server. 



SYNOPSIS 

/usr/libexec/ rpc . rwalld 

D ESC RIPTIO N 

rpc.rwaiid isaserver thatwill send a messageto users currently logged into thesystem. Thisserver invokesthewaii(l) 
command to actually wri te the messages to thesystem. 

Messages aresent to this server by the rwaii(l) command. Therpc.rwaiid daemon isusually invoked by inetd(8). 

rpc.rwalld USesan RPC protocol defined in /usr/include/rpcsvc/rwall.x. 

SEEALSO 

rwall(l), wall(l), inetd(8) 

BSD 4.3, 7 Junel993 

rpcinfo 

rpcinfo— Report RPC information. 
SYNOPSIS 

rpcinfo -p [host ] 

rpcinfo [-n portnuin] -u host program [version] 

rpcinfo [-n portnum] -t host program [version] 

rpcinfo -b program version 

rpcinfo -d program version 

DESCRIPTION 

rpcinfo makesan RPC cali to an RPC server and reportswhat itfinds. 
OPTIONS 

-p Probe the port mapper on host and print a list of ali regi stered RPC programs. If host is 

not specified, it defaultsto thevaluereturned by nostname(l). 
-u M akean RPC cali to procedure 0 of program on the specified host using U D P and 

report whether a responsewas received. 
-t M akean RPC cali to procedureO of program on the specified host usingTCP and report 

whether a responsewas received. 
-n U se port no m as the port numberforthe -t and -u options instead of the port number 

given by the port mapper. 
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■ b M akean RPC broadcast to procedure 0 of the specified program and versi o n using U D P 

and report ali hoststhat respond. 
■d D elete registration fortheRPC serviceof the specified program and versi on. Thisoption 

can be exercised only by the superuser. 

The program argument can beeither a nameor a number. If a versi on is specified, rpcinfo attemptsto cali that versi on of the 
specified program. Otherwise, rpcinfo attemptsto find ali theregistered versi on numbersfor the specified program by calling 
versi on 0 (which ispresumed notto exist; if it doesexist, rpcinfo attemptsto obtain thisinformation by calling an extremely 
high version number instead) and attemptsto cali each registered version. N ote that the versi on number isrequired for -b 
and -d options. 

EXAMPLES 

To show ali the RPC servi ces registered on the locai machine, use 

rpcinfo -p 

To show ali of the RPC servi ces registered on the machine named klaxon, use 

rpcinfo -p klaxon 

To show ali machineson the locai net that arerunningtheYellow Pagesservice, use 

rpcinfo -b ypserv 'version' -- uniq 

'version 1 is the current Yellow Pages version obtained from the results of the -p switch above. 
To delete the registration for version 1 of thewaiid servi ce, use 

rpcinfo -d walld 1 

SEEALSO 

rpc(5), portmap(8), RPC Programming G uide 
BUGS 

In releases priorto SunOS 3.0, theN etwork Fi le System (N FS) did not register itself with theport mapper; rpcinfo cannot 
beused to makeRPC Calisto the NFS server on hostsrunningsuch releases. 

17 Decemberl987 



rquotad, rpc.rquotad 

rquotad, rpc.rquotad— Remote quota server. 
SYNOPSIS 

/usr/etc/rpc. rquotad 

DESCRIPTION 

rquotad is an rpc(3N ) server that returnsquotasfor a user of a locai filesystem that ismounted by a remote machine over the 
N FS. The results are used by quota(l) to display user quotasfor remote filesystems. The rquotad daemon isusually started at 
boot ti me from therc.net script. 

FILES 

quotas Q uota fi le at the filesystem root 

SEEALSO 

quota(l), rpc(3N), nfs(4P), services(5) inetd(8C) 



17 Decemberl987 




rshd 

rshd— Remote shell server. 
SYNOPSIS 

rshd [-alnL] 

DESCRIVO N 

The rshd server is the server for the rcmd(3) routine and, consequently, forthersh(l) program. The server provides remote 
execution facilitieswith authentication based on privileged port numbersfrom trusted hosts. 

The rshd server listensfor servicerequestsat the port indicated in thecmd servi ce specificati on; seeservices(5). When a 
servi ce request is received, the followi ng protocol is initi ated : 

1. The server checks the client's source port. If the port isnot in the range 512-1023, the server aborts the connection. 

2. The server readscharactersfrom thesocket up to a nuli (\b) byte. The resultant stri ng isinterpreted asan ASCII 
number, base 10. 

3. If the number received in Step 2 is nonzero, it isinterpreted as the port number of asecondary stream to beused for the 
stderr. A second connection isthen created to the specified port on the client's machine. The source port of thissecond 
connection is also in the range 512-1023. 

4. Theserver checks the client's source address and requeststhecorresponding hostname(seegethostbyaddr(3), hosts(5), 
and named(8)). If the hostname cannot be determi ned, thedot-notation representati on of the host address isused. If the 
hostnameisin the same domain as the server (accordi ngto thelasttwo componentsof the domain name), or if the - a 
option isgiven, the addresses for the hostname are requested, verifying that the name and address correspond. If address 
verification fails, the connection is aborted with themessage, Host address mismatch. 

5. A nul I-termi nated usernameof at most 16 characters is retri eved on the initi al socket. Thisusernameis interpreted as 
the user identity on the client's machine. 

6. A nul I-termi nated usernameof at most 16 characters is retri eved on theinitial socket. Thisusernameis interpreted asa 
user identity to useon theserver's machine. 

7. A nul I-termi nated command to bepassed to a shell is retri eved on theinitial socket. The length of thecommand is 
limited by the upper bound on the sizeof the system 's argument list. 

8. rshd then validates the user usi ng ruserok(3), which usesthefileand thefilefound in theuser's home directory. The -ì 
option prevents ruserok(3) from doingany validation based on theuser's .mosts file, unlesstheuser isthesuperuser. 

9. A nuli byte isreturned on theinitial socket and thecommand lineispassed to thenormal login shell of the user. The 
shell inherits the network connections established byrshd. 

Tran sport- leve! keep-alivemessagesareenabled unlessthe -n option ispresent. The use of keep-alivemessages al lows sessi ons 
to betimed out if the eli ent crashesor becomesunreachable. 

The -l option causesall successful accessesto belogged to sysiogd(8) asauth.into messagesand ali failed accessesto be 

logged as auth.notice. 

DIAGNOSTICS 

Except for the last one listed, ali diagnostic messages are return ed on theinitial socket, after which any network connections 
areclosed. An errar is indicated by a leading byte with a valueof 1 (0 isreturned in Step 9 upon successful completi on of ali 
the stepspri orto theexecution of thelogin shell). 

ucuser too long. T he name of the user on the client's machi ne is longer than 16 characters. 

Ruser too long. T he name of the user on the remote machine is longer than 16 characters. 

command too long. T he command line passed exceeds the size of theargument list (as configured i nto the 

system). 

Login incorrect. N o password file entry for the username existed. 

Remote directory. T he chdir command to the home directory fai led. 
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Permission denied. 
Can't make pipe. 
Can't fork; try again. 
<s h e I I n a me > : ... 



The authentication procedure described previously failed. 
T he pi pe needed for the stderr wasn't created. 
A fork by the server fai led. 

Theuser'slogin shell could not bestarted. Thismessageis return ed on the connection 
associ ated with the stderr and is not preceded by a flag byte. 



SEEALSO 

rsh(l), rcmd(3), ruserok(3) 

BUGS 

The authentication procedure used hereassumestheintegrity of each client machine and theconnecting medium. This is 
insecurebut isuseful in an "open" environment. 

A faci I ity to allow ali data exchangesto beencrypted should bepresent. 

A more extensible protocol (such asTelnet) should beused. 

BSD 4.2, 30 Aprii 1991 



rwhod 

rwhod— System status server. 
SYNOPSIS 

rwhod 

D ESC RIPTIO N 

rwhod is the server that mai ntains the database used bytherwho(l) and ruptime(l) programs. Itsoperation ispredicated on 
the abi lity to broadcast messageson a network. 

rwhod operates as both a producer and consumer of status information. As a producer of information, it periodically queries 
the state of the system and con structs status messagesthat are broadcast on a network. As a consumer of information, it 
listensfor other rwhod servers' status messages, vai i dati ngthem and then recordi ngthem in acollection of fileslocated in the 
directory. 

The server transmitsand receives messages at the port indi cated in therwho servi ce specificati on; seeservices(5). The 
messages sent and received areof theform: 

struct outmp { 

char out_line [8] ; /* tty name */ 

char out_name[8] ; /* user id */ 

long out_time; /* time on */ 

>; 



struct whod { 

char wd_vers; 

char wd_type; 

char wd_fill[2]; 

int wd_sendtime; 

int wd_recvtime ; 

char wd_hostname[32] ; 

int wd_loadav[3] ; 

int wd_boottime ; 

struct whoent { 

struct outmp we_utmp; 
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int we_idle; 
} wd_we[1024 / sìzeof (struct whoent)]; 

}; 

Ali fieldsareconverted to network byteorder prior to transmission. Theload averagesareascalculated by thew(l) program 
and represent load averagesover the 5-, 10-, and 15-minute intervals prior to a server's transmission; they are multipli ed by 
100 for representation in an integer. Thehostnameincluded isthat returned by thegethostname(2) system cali, with any 
trai li ng domain name orni tted. The array at the end of the message contai ns information abouttheusers logged in to the 
sending machine This information includesthecontentsof theutmp(5) entry for each non-i die terminal line and avalue 
indicati ng the ti me in secondssincea character was last received on the terminal line. 

M essages received by therwho server arediscarded unless they ori ginated at an rwho server's port. In addition, if the host's 
name, asspecified in the message, contai ns any unpri ntable ASC 1 1 characters, the message isdiscarded. Valid messages 
received by rwhod areplaced in files named in the directory. These filescontain only themost recent message, in the format 
described previously. 

Status messages are generated approximately onceevery threeminutes. rwhod performsan mist(3) every 30 minutesto guard 
against the possibility thait thisfile is not the system i m age cu rrentl y o perati n g. 

SEEALSO 

rwho(l), ruptime(l) 

BUGS 

Thereshould bea way to relay status information between networks. Status information should besent only upon request 
rather than continuously. Peopleoften interpret the server dying or network communication failures as a machine going 
down. 

HI STORY 

The rwhod command appeared in BSD 4.2. 

BSD 4.2, 16 March 1991 



sendmail 

sendmaii— Send mail over the Internet. 
SYNOPSIS 

sendmail [f I ags ] [addr es s . . . ] 

newaliases 

mailq [-v] 

smtpd 

bsmtp 

runq 



DESCRIVO N 

sendmail sendsa messageto oneor more recipiente routing the message over whatever networks are necessary. sendmail does 
internetwork forwarding as necessary to deli ver the messageto the correct place. 

sendmaii isnot intended asauser interface routine. Other programs provide user-friendly front ends. sendmaii isused only to 
deli ver preformatted messages. 

With no flags, sendmaii reads its standard input up to an end-of-fileor a lineconsistingonly of a single dot and sendsa copy 
of the message found thereto ali the addresses listed. It determi nes the networks to usebased on thesyntaxand contentsof 
theaddresses. 
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Locai addressesarelooked up in afileand aliased appropriately. Aliasi ng can be prevented by precedingtheaddresswith a 
backslash. Usually, thesender isnot included in any alias expansions; for example, if john sendsto group and group includes 
john in theexpansion, then the letter will not bedelivered to john. 

Flagsare 

■ ba Go into ARPAN ET mode. Ali input linesmust end with a CR-LF, and ali messageswill 

begenerated with aCR-LF attheend. Also, theFrom: and Sender: fieldsareexamined 
for the name of the sender. 

■ bd Run asa daemon. Thisrequires Berkeley I PC. sendmaii will fork and run in the 

background, listening on socket 25 for incoming SM TP connections This is usually run 

from /etc/rc. 

-bi I ni tialize the alias database. 

-bui Deliver mail in theusual way (default). 

-bp Print a listing of thequeue. 

-bs UsetheSM TP protocol asdescribed in RFC 821 on standard input and output. This 

flag impliesall theoperationsof the - ba flagthat are compati ble with SMTP. 

-bb Read batched SMTP (BSMTP) commandsfrom standard input. 

-bt Run in addresstest mode. This mode reads addresses and showsthestepsin parsi ng; it is 

used for debugging confi guration tables. 

-bv Verify namesonly; do not try to col lect or deliver a message. Verify mode is usually used 

for validating usersor mailing lists. 

-bz Create the configuration freezefile. 

-c file Use alternate confi guration file sendmaii refusesto run asrootif an alternate configura- 

tion file is specified. Thefrozen configuration fileis bypassed. 
-d x Set debugging valuetox. 

-f full name Set the fui I name of the sender. 

-t name Sets the name of the "from" person (thesender of the mail), -t can only be used by 

trusted users (usually root, daemon, and network) or if the person you aretryingto 
becomeisthesameas the person you are. 

-h n Set thehop countto n. Thehop count isincremented every ti me the mail is processed. 

When it reachesa limit, the mail isreturned with an errar message, the vieti m of an 
aliasi ng loop. If not specified, Received: lines in the message are counted. 

-n Don'tdo aliasing. 

-o x vai uè Set option x to the specified «ai ne. 0 ptions are described later in this section. 

-q ti me Processed saved messages i n the queue at given i ntervals. If t i me isomitted, processthe 

queueonce. ti me is given asatagged number, with s bei ng seconds, m being minutes, n 
bé ng hours, d being days, and w being weeks. For example, -qih30m or -q90m both set the 
time-outto 1 hour, 30 minutes. If ti me isspecified, sendmaii runsin background. This 
option can beused safely with -bd. 

-m i dent Processthequeued message with thequeuelD i dent . 

-R addr Process the queued messages that have the stri ng a d d r in one of the recipient addresses. 

-s addr Process the queued messages that have the stri ng a ddr in thesender address. 

-r name An alternate and obsoleteform of the -f flag. 

-t Read message for recipiente To:, Ce:, and Bcc: lines are scan ned for recipient addresses. 

TheBcc: line is del eted beforetransmission. Any addresses in theargument listare 
suppressed; that is, they do not receivecopieseven if listed in the message header. 

-v Go into verbose mode. Alias expansions are announced and so on. 
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Therearealso a number of processing opti onsthatcan beset. Usuai ly, thesewill only beused by a system administrator. 
Optionscan beset either on thecommand li ne usi ng the -o flag or in the configurati on file. These are described in detail in 
theSendmail Installation and Operati on Guide Theoptions are 

a tue Use alternate aliasfile. 

c On mailersthatareconsidered "expensive" to connectto, don't initiate immediate 

connection. This requires queuing. 

d x Set the delivery modeto %. Delivery modesarei for interactive(synchronous) delivery, 

b for background (asynchronous) delivery, and q for queue only (actual delivery isdone 
the next ti me the queue is run). 

d Try to automatically rebuild the alias database if necessary. 

e x Set error processing to mode x. Vali d modesarem to mail back the errar message, w to 

"write" back the error message (or mail it back if thesender isnot logged in), p to print 
theerrorson the terminal (default), q to throw away error messages(only exit status is 
returned), and eto do special processing for the BerkN et. If the textof the message is 
notmailed back by modesm or w and if thesender is locai to this machine, a copy of the 
message isappended to the fi le in the sender's home directory. 

f mode The modeto usewhen creating temporary files. 

f SaveU N IX-styleFrom: I inesat the front of messages. 

g n T he default group ID to usewhen calling mailers. 

h f il e TheSM TP help file 

i Do nottakedotson a linebythemselvesasamessageterminator. 

k n Checkpoint the queue fi le after everyN successful deliveries {default is 10). This avoids 

excessive duplicate deliverieswhen sendingto long mailing lists interrupted by system 

crash es. 

l n The log level. 

m Send also to "me" (thesender) if I am in an alias expansion. 

0 If set, this message may haveold style headers. If notset, this message isguaranteed to 

havenew style headers (commasinstead of spaces between addresses). If set, an adaptive 
algorithm isused thatwill correctly determinetheheaderformatin mostcases. 

q queuedi r Sei ect th e d i recto ry in which to queue messages 

r ti meout Thetime-out on reads; if none is set, sendmail will waitforever for a mailer. Thisoption 

violates the word (if nottheintent) of the SMTP specification, so the t i meout should 
probably befairly large. 

sfile Save stati stics in thenamed file. 

s Always instantiatethequeuefile, even under circumstanceswhereit isnotstrictly 

necessary. This provi des safety against system crashes during delivery. 

t t i me Set thetime-out on undelivered messages in the queue to the specified ti me. After 

delivery hasfailed (for example, becauseof a host being down) for this amount of ti me, 
failed messages will be returned to thesender. The default isthreedays. 

tstz.dtz Setthenameof thetimezone. 

u user data base If set, auser database is consulted to getforwarding information. You can consider this 

an adjunct to the al iasi ng mechanism, exceptthat the database isintended to be 
distri buted; aliases are locai to a parti cular host. This might not be avai lable if your 
sendmail does not havethe userdb option compiled in. 

un Set the default user ID for mailers. 

w If notset, name server lookupswill use a query type of any to find types cname, a, and mx 

and will cause ali existing recordsto becached by the locai server. If thereis (or might 
be) a wildcard mx in the locai domain or its parents that are searched, you must set this 
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option, which usesa query typeof cname only; otherwise, it causes ali fully qualified 
namesto match asnames in the locai domain. 

In aliases, the first eh aracter of a namecan bea vertical bar to cause interpretation of therest of thenameasacommand to 
pipe the mail to. It might be necessary to quote the nameto keep sendmaii from suppressingtheblanksbetween arguments. 
Forexample, a common alias is 

msgs: " ] /usr/bin/msgs -s" 

Aliases can also havethesyntaxto ask sendmaii to read thenamed file fora list of recipients. For example, an alias such as 

poets: " : include: /usr/local/lib/poets.list" 

would read for the list of addresses making up thegroup. 

sendmaii returnsan exit status describi ngwhat it did. T he codes are defi ned in sysexits.n: 
ex_ok Successful completion on ali addresses. 

ex_nouser Usernamenotrecognized. 

ex_unavailable Catchall meani ng necessary resources were not avai lable. 

ex_syntax Syntax errar in address. 

ex_software Internai software errar, includi ng bad arguments 

ex_oserr Temporary operating system error, such as cannot fork. 

ex_nohost Hostnamenotrecognized. 

ex_tempfail M essagecould not besent immediately butwasqueued. 

If invoked asnewaiiases, sendmaii rebui Ids the alias database. If invoked asmaiiq, sendmaii pri nts the contentsof the mail 
queue. If invoked assmtpd, sendmaii forksand runsasadaemon. If invoked asbsmtp, sendmaii processes batched SMTP on 
standard input. If invoked asrunq, sendmaii runsthrough the mail queue and makeswhat del iveries are possi ble. 

FILES 

Exceptforthefile /etc/sendmaii.cf itself, thefollowing pathnamesareall specified in /etc/sendmaii.cf.Thus, thesevalues 
are only approximations. 

/etc/aiiases raw data for alias names 

/etc/aliases.pag 

/etc/aiiases.dir database of alias names 
/etc/sendmaii.cf confi guration file 
/etc/sendmaii.fc frozen configuration 

/etc/sendmail.hf help file 
/var/log/sendmail.st COllected Stati Sti CS 
/var/spool/mqueue/* temp files 

SEE ALSO 

binmaii(l), maii(l), rmaii(l), sysiog(3), aiiases(5), maiiaddr(7), rc(8); DARPA Internet Request for C omments RFC 819, 
RFC 821, RFC 822; "Sendmaii: An Internetwork M ail Router," SM M and N 0.16, "Sendmaii Installati on and Operation 
Guide," SM M and N o.7. 

HI STORY 

The sendmaii command appeared in BSD 4.2. 

BSD 4, 5 August 1991 



S6tS6TÌ3l 1391 



setfdprm 

setfdprm— Sets user-provided floppy disk parameters. 



SYNOPSIS 

setfdprm 
setfdprm 
setfdprm 
setfdprm 
setfdprm 



-p ] device name 

- p ] devi ce s ì z e s e c t o r s h e a d s t r a c k s s t r e t c h gap rate s p e c 1 f mt _ g a p 

-c ] devi ce 

-y ] device 

-n ] device 



DESCRIVO N 

setfdprm is a uti lity that can beused to load disk parameters into the auto-detecting floppy devi ces, to clear old parameter 
sets, and to disableor enable diagnostic messages. 

Without any options, setfdprm loadsthe device (usuai ly /dev/fda or /dev/fdi) with a new parameter set with the name entry 
found in /etc/fdprm (usually named 360/360 and so on). These parameters stay in effect unti I the media ischanged. 

OPTIONS 

-p device name Permanently loads a new parameter set for the specified auto-configuring floppy device 

for theconfiguration with name in /etc/fdprm. Alternative^, the parameters can begiven 
directly from thecommand line. 

-c d e v i c e C lears the parameter set of the specified auto-conf iguri ng floppy devi ce. 

-y device E nables format detection messages for the specified auto-configuring floppy device. 

-n devi ce D isables format detection messages for the speci fi ed auto-configuring floppy device 

BUGS 

Thisdocumentation isgrossly incomplete. 
FILES 

/etc/fdprm 

AUTHOR 

W emer Almesberger (almesber@nessie . cs . id . ethz . eh) 

Linux 0.99, 20 N ovember 1993 



setserial 

set se nai— G et/set Linux serial port information. 
SYNOPSIS 

setserial [ -abqvVW ] device [ parameterl [ arg ] ] ... 
setserial -g [ -abv ] devicel ... 

DESCRIPTION 

setserial isaprogram designed to set or report theconfiguration information associateci with aserial port. This information 
includeswhat I/O port and IRQ a parti cui ar serial port is usi ng, whether the break key should be i nterpreted astheSecure 
Attention Key, and so on. 

Duringthenormal bootup process, only COM ports 1-4 are initialized, using thedefault I/O ports and I RQ values, as 
listed. To initialize any addi tional serial ports, orto changetheCOM 1-4 ports to a nonstandard configuration, the 
setserial program should beused. Typically, it iscalled from an re. serial script, which is usually run out of /etc/rc. locai. 
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Thedeviceargumentorargumentsspecifytheserial device that should beconfigured or interrogated. Itwill usually havethe 
followingform: /<jev/cua[e-3]. 

If no parametersarespecified, setseriai printsthe port type (such as8250, 16450, 16550, 16550A), the hardware I/O port, 
the hardware IRQ line, its "baud base," and someof itsoperational flags 

If the -g option isgiven, theargumentsto setseriai are interpreted asa list of devicesforwhich thecharacteristicsof those 
devices should beprinted. 

Without the -g option, the first argument to setseriai is interpreted as the devi ceto bemodified or characteristicsto be 
printed, and any additi onal arguments are interpreted as parameters that should beassigned to that serial device. 

Forthemost part, superuser privilegeis required to set theconfiguration parameters of a serial port. A few serial port 
parameters can beset by normal users, however, and thesearenoted asexceptionsin thismanual page. 

0PTI0NS 

setseriai accepts the following options: 

-a When reporti ng theconfiguration of aserial device, printall available information. 

■ b When reporti ng theconfiguration of aserial device printasummaryof thedevice's 

confi guration, which might besuitablefor printing duri ng the bootup processduring 

the /etc/rc script. 

-q Bequiet. setseriai will printfewer linesof output, 

-v Beverbose. setseriai will printadditional status output, 

-v D isplay version and exit, 

-w Do wild interrupt initialization and exit. 

PARAMETERS 

Thefollowing parameters can beassigned to a serial port. 

Ali argument valuesareassumed to bein decimai uniess preceded byax. 

port p o r t _ n u mb e r The port opti on sets the I/O port asdescribed previ ously. 

irq i r q_ n u mbe r T he irq option sets the hardware I RQ asdescribed previously. 

uart uart type This option is used to set the U ART type. T he permitted types are none, 8250, 16450, 

16550, and 16550A. Because the 8250 and 16450 UARTsdo not haveFIFOs, and 
becausethe originai 16550 havebugsthat maketheFIFOsunusable, the FIFO will only 
beused on chips identified as 16550A UARTs. SettingtheUART typeto 8250, 16450, 
or 16550 will enable the serial port without tryingto usetheFIFO. UsingtheUART 
type none will disablethe port. Some internai modemsarebilled ashavinga"16550A 
UART with alKB buffer." This isa lie. They do not really havea 16550A-compatible 
UART; instead, what they have isa 16450-compatible UART with a 1KB receive buffer 
to prevent receiver overruns. This isimportant because they do not haveatransmit 
FIFO. H enee, they are not compati ble with a 16550A UART, and theautocon- 
fi guration processwill correctly identify them asl6450s. If you atterri ptto overridethis 
usi ng the uart parameter, you seedropped characters during fi le transmissions These 
UARTs usually haveother problems: Theskip test parameter also often must be 
speci fi ed. 

autocontig When this parameter isgiven, setseriai asks the kernel to atterri pt to automati cally 

configure the seri al port. The I/O port must be correctly set; the kernel will atterri ptto 
determinetheUART type, and if theauto_irq parameter isset, Linux will attemptto 
automatically determi ne the IRQ . Theautocontigure parameter should begiven after 
the port, autoj.rq, and skip_test parameters h ave been specified. 



setserial 



D u ri n g autoconf i gu rati o n , try to determ i ne the IRQ. T his f eatu re i s n ot guaranteed to 
always produce the correct result; somehardwareconfigurationswill fool theLinux 
kernel. It is general ly safer not to usetheauto_irq feature but rather to speci fy the IRQ 
to beused explicitly, using the irq parameter. 
Duringautoconfiguration, do not try to determinetheIRQ. 
During autoconfiguration, ski p the U ART test. Some internai modemsdo not have 
N ational Semiconductor compatibleUARTsbut have cheap im itati ons instead. Someof 
thesecheesy imitati on UARTsdo not fully support the loopback detection mode, which 
isused by the kernel to makesuretherereally isaUART at a parti cui ar add ress before 
attempting to configure it. For certain internai modems, you will need to speci fy this 
parameter so Linux can initializetheUART correctly. 
Duringautoconfiguration, do not ski p the U ART test. 

Thisoption sets the base baud rate, which is the clock frequency divided by 16. Usuai ly, 
thisvalue is 1 15200, which isalso thefastest baud rate, which the U ART can support. 
Use 57.6KB when the application requests 38.4KB. Thisparameter can bespecified by 
anon-privileged user. 

Use 115KB when the application requests 38.4KB. Thisparameter can bespecified by a 
non-privileged user. 

Usethecustom divisorto setthespeed when the application requests 38.4KB. In this 
case, the baud rate is the baud_base divided by the divisor. Thisparameter can be 
specified by a non-privileged user. 

Use 38.4KB when the application requests 38.4KB. Thisparameter can bespecified by 
a non-privileged user. 

Thisoption sets the custom divisor. This divisor wi II beused when thespd_cust option 

i s sei ected and the serial port is setto 38.4KB by the application. This parameter can be 

specified by a non-privileged user. 

Set the break key attheSecureAttention Key. 

D isablethe Secure Attention Key. 

C onfigure the port as an AST Fourport card. 

DisableAST Fourport configuration. 

Specify theamount of time, in hundredthsof asecond, that DTR should remai n low on 

aseri al line after the callout deviceisclosed before the blocked dial-in device raises DTR 

again. The default valueof thisoption issa, or a half-second delay. 

Lock out callout port (/dev/cuaxx) accessesacrossdifferent sessi ons. That is, once a 

processhasopened a port, do not al low a processwith adifferent sessi on ID to open 

that port until the first processhasclosed it. 

D 0 not lock out callout port accesses across different sessions. 

Lock out callout port (/dev/cuaxx) accesses across different process groups. That is, once 

a process has opened a port, do not allow a process in a different process group to open 

that port until the first processhasclosed it. 

D 0 not lock out callout port accesses across different process groups. 

Notify a process blocked on opening a dial-in linewhen a process has fi ni shed usinga 

callout li ne (either by closing it or by the serial line bei ng hung up) by returni ng eagain 

to the open. 

The application of thisparameter isfor gettys that are blocked on aseri al port'sdial-in 
line This al lows the getty to reset the modem (which may havehad its configuration 
modified by the application using the callout devi ce) before blockingon theopen again. 
Do not notify a process blocked on opening a dial-in linewhen the callout device is 
hung up. 
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spnt_termios T reat the terni i os setti ngs used by the callout device and the termios setti ngsused bythe 

dial-in devices as separate. 

"spiit_termios U se the same termi os structure to storeboth the dial-in and callout ports. Thisisthe 

default option. 

caiiout _nohup If this particular serial port isopened as a callout device, do not hangup thetty when 

carrier detect is dropped. 

"caiioutnohup Do notskip hanging up thetty when a serial port isopened as a callout device Of 

course, theHUPCL termios flag must beenabled if thehangup isto occur. 

CON SIDERATIO NSOFCONFIGURING SERIAL PO RTS 

It is important to notethat setsenai merely tellsthe Linux kernel whereit should expect to find the I/O port and IRQ lines 
of a particular serial port. It doesnot configure the hardware, theactual serial board, to use a particular I/O port. To do that, 
you need to physically program the serial board, usually by setti ng somejumpersor by switching some D IP switches. 

This section providessomepointersin helping you decide how you wantto configure your serial ports. 

The "standard M S-DOS" port associ ations are 

/dev/ttyS0(COMl), port0x3f8 IRQ 4 

/dev/ttysi (COM2), port 0x2f8 IRQ 3 

/dev/ttyS2 (COM 3), port0x3e8 IRQ 4 

/dev/ttyS3(COM4), port0x2e8 IRQ 3 

Dueto thelimitationsin the design of theAT/ISA busarchitecture, an IRQ li ne usually cannot beshared between two or 
more serial ports. If you attemptto do this, oneor both serial ports wi II become unreliable if you try to useboth simulta- 
neously. This limitation can beovercomeby special multi port serial port boards, which aredesigned to share multi pie seri al 
ports over a single IRQ line. M ulti port serial cardssupported by Linux include theAST FourPort, theAccent Async board, 
the Usenet Seri al II board, theBocaboard BB-1004, BB-1008, and BB-2016 boards, and the H U B-6 serial board. 

Theselection of an alternative IRQ line isdifficult because most of them are al ready used. The followi ng table lists the 
"standard M S-DOS" assignmentsof available IRQ lines: 

IRQ 3 COM2 

IRQ 4 COMI 

IRQ 5 LPT2 

IRQ 7 LPT1 

M ost peoplefind that IRQ 5 isagood choice, assumi ng that thereisonly one parai lei port active in the computer. Another 
good choiceis IRQ 2 (a.k.a. I RQ 9), although thislRQ issometimes used by network cards, and very rarelywill VGA cards 
beconfigured to use IRQ 2 as averti cai retrace interrupt. If your VGA card isconfigured thisway, try to disableit so you 
can reclaim that IRQ linefor someother card. It'snot necessary for Linux and most other operati ng systems. 

Theonly other available IRQ lines are 3, 4, and 7, and these are probably used bythe other serial and parai I el ports. (Ifyour 
serial card hasa 16-bit card edgeconnectorand supports higher interrupt numbers, then IRQ 10, 11, 12, and 15 arealso 
available.) 

On AT class machines, IRQ 2 isseen asIRQ 9, and Linux will interpret it in thismanner. 

I RQs other than 2 (9), 3, 4, 5, 7, 10, 11, 12, and 15 should not beused because they are assi gned to other hardware and 
cannot, in general, bechanged. H ere are the "standard" assignments: 

IRQ 0 Timer channel 0 

IRQ 1 Keyboard 

IRQ 2 Cascade for controller 2 

IRQ 3 Serial port 2 

IRQ 4 Serial port 1 



IRQ 5 


Parai lei port 2 (Reserved in PS/2) 


IRQ 6 


Floppy diskette 


IRQ 7 


Parai lei port 1 


IRQ 8 


Real-ti me clock 


IRQ 9 


Redirected to IRQ 2 


IRQ 10 


Reserved 


IRQ 11 


Reserved 


IRQ 12 


Reserved (Auxiliary device in PS/2) 


IRQ 13 


M ath coprocessor 


IRQ 14 


H ard disk controller 


IRQ 15 


Reserved 


CAUTION 





Usingan invalid portcan lock up your machine. 
FILES 

/etc/rc. locai 
/etc/rc. serial 

SEEALSO 

tty(4), ttys(4), kernel/chr_drv/serial.c 

AUTHOR 

The originai versi on of setseriai waswritten by Rick Sladkey (jrseworid.std.com) and wasmodified by M ichad K. Johnson 

(johnsonm9stolaf.edu). 

Thisversion hassincebeen rewritten from scratch byTheodoreTs'o (tytsoemit.edu) on 1/1/93. Any bugsor problemsare 
solely hisresponsibility. 

tìsarial 2.10, 27 August 1994 

setsid 

setsid— Run a program in a new session. 
SYNOPSIS 

setsid program [ ar g ... ] 

DESCRIPTION 

setsid runsa program in a new session. 

SEEALSO 

setsid(2) 

AUTHOR 

Rick Sladkey (jrs@world. std.com) 

Linux 0.99, 20 Novemberl993 
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showmount 

showmount— Show mount informati on for an N FS server. 
SYNOPSIS 

/usr/etc/ showmount [ \ -adehv\ ] [ \ - -all\] [\ - - direct ories \ ] 
[ \ - -exports\] [\ - -help\] [\--version\ ] [\host \] 

D ESC RIPTIO N 

showmount queries the mount daemon on a remote host for information about the state of the N FS server on that machine. 
With no options, showmount I i sts th e set of clientswho aremountingfrom that host. The output from showmount isdesigned 
to appear asthough itwere processed through sort -u. 

OPTIONS 

-a Or --ali 
-d Or - -directories 
-e or - -exports 
-h Or--help 
-v Or - -version 
- -no-headers 

SEEALSO 

rpc.mountd(8), rpc.nfsd(8) 

BUGS 

Thecompletenessand accuracy of the information that showmount di spi ays vari es accordi ngto theN FS server's implementa- 
ti on. Because showmount sortsand uniques the output, it is impossibleto determi ne from the output whether a client is 
mounting the same directory morethan once 

AUTHOR 

Rick Sladkey (jrs@world. std.com) 

6 October 1993 



List both the client hostnameand mounted directory in host : d i r format. 

List only the di rectories mounted by some client. 

Show the N FS server's export list. 

Providea short help summary. 

Report the current version number of the program. 

Suppress the descri pti ve headi ngs from the output. 



shutdown 



shutdown— Closedown the system. 
SYNOPSIS 



shutdown [ -h 
reboot [ -ti ] 
fastboot [ -h 
halt [ -h | -r 
fasthalt [ -h 



r 1 I 



] [ -fqs ] [ now 

fqs ] [ now ! 

r ] [ -fqs ] [ now 

[ -fqs ] [ now | hh 

r ] [ -fqs ] [ now 



hh: ss | +mi ns 
h: ss ! +mi n s ] 

hh: ss | +mi ns 
ss | +mi n s ] 

hh: ss I +mi ns 



DESCRIPTION 

In general, shutdown prepares the system for a power down or reboot. An absoluteor delta ti me can begiven, and periodi c 
messageswill besentto ali userswarning of the shutdown. 

halt ÌS the Same as shutdown -h -q now. 
fasthalt ÌS the Same as shutdown -h -q -f now. 



reboot ÌS the Same as shutdown -r -q now. 



fastboot isthe Same as shutdown -r -q -f now. 

The default delta ti me if none is specified, istwo minutes. 

Fi ve mi nutesbefore shutdown (or immediately, if shutdown islessthan fiveminutesaway), the /etc/noiogin fileiscreated 
with a message stati ng that the system isgoing down and that loginsareno longer pernii tted. Theiogin(l) program will not 
allow non-superusersto log in duringthisperiod. A message will besentto ali usersatthistime. 

When theshutdown timearrives, shutdown notifi esali users, tei Is ±nit{8) notto spawn moregetty(8)s, writes the shutdown 
timeinto the /var/iog/wtmp file killsall other processeson the system, sync(2)s, unmountsall the disks, sync(2)sagain, waits 
for asecond, and then either terminates or reboots the system. 



OPTIONS 



H alt the system. D o not reboot. Thisoption isused when powering down the system. 
Reboot the system. 

Fast. When the system isrebooted, the fi lesystems will not bechecked. Thisisarranged 
by creati ng /fastboot, which /etc/rc must detect (and delete). 
Quiet. Thisuses a default broadcast message and doesnot prompt the user for one. 
Rebootin single-user mode. Thisisarranged by creating /etc/singieboot, which 
simpieinit(8) detects(and deletes). 



FILES 



/etc/rc 

/fastboot 

/etc/singleboot 

/etc/nologin 

/var/log/wtmp 

SEEALSO 

umount(8), login(l), reboot(2), simpleinit(8), init(8) 

BUGS 

U nli ke the BSD shutdown, users are notifi ed of shutdown only onceortwice, instead of many times, and at shorterand 
shorter i ntervals as "apocalypse approaches." 

AUTHOR 

poe@daimi.aau.dk. M Odified by jrs@world.std.com. 

Linux 0.99, 20 N ovember 1993 



simpleinit 

simpieinit— Process control initialization. 
SYNOPSIS 



init [ single ] 
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DESCRIVO N 

init isinvoked asthelast step in the Linux boot sequence If the single option isused, or if the file /etc/singieboot exists, 
then single-user mode wi II beentered, by starti ng /bin/sh. If thefile /etc/securesingie exists, then theroot password will be 
required to start single-user mode. If theroot password doesnot exist, or if /etc/passwd does not exist, thecheckingof the 
password will beskipped. 

If thefile /etc/Tz exists, then thecontentsof thatfilewill beread and used to set theiz environment variablefor each 
process started by simpieinit. This "feature" isonly availableif it's configured at compi le ti me It'snot usually needed. 

After single-user mode is termi nated, the /etc/rc file isexecuted, and theinformation in /etc/inittab will beused to start 
processes. 

W hile imt isrunning, several signals are trapped with special action taken. Becauseinit hasPID 1, sending signalsto the 
init process is easy with the kiii(l) command. 

If init catchesa sighup (hangup) signal, the /etc/inittab will beread again. If init catchesasiGTSTP (terminal stop) signal, 
no more processes will bespawned. Thisisatoggle, which is reset if init catch esanother sigtstp signal. 

If init catches a sigint (interrupt) signal, init will sync a few timesand try to start reboot. Failing this, init will executethe 
system reboot(2) cali. Under Linux, it ispossibleto configure the C tri -tAlt+D el sequence to send a signal to init instead of 
rebooting the system. 

THE inittab FILE 

Becauseof thenumber of init programsthat areappearing in the Linux community, the documentati on forthe 
/etc/inittab file which isusually found with theinittab(5) man page, ispresented here: 

Theformat is 

ttyline: termcap- entry :getty- command 

An examplefollows: 

ttyl :console: /sbin/getty 9600 ttyl 
tty2:console: /sbin/getty 9600 tty2 
tty3:console: /sbin/getty 9600 tty3 
tty4:console: /sbin/getty 9600 tty4 

# tty5:console: /sbin/getty 9600 tty5 

# ttyS1 :dumb: /sbin/getty 9600 ttyS1 

# ttyS2:dumb: /sbin/getty -m -t60 2400 ttyS2 

Lines beginning with the # character aretreated ascomments. Pleaseseedocumentation forthegetty(8) command thatyou 
are usi ng becausethere are several of thesein the Linux community at this ti me. 

FILES 

/etc/inittab 

/etc/singleboot 

/etc/securesingle 

/etc/TZ 

/etc/passwd 

/etc/rc 



SEEALSO 

inittab(5), ctrlaltdel(8) reboot(8), termcap(5), getty(8), agetty(8), shutdown(8) 



BUGS 

This program iscalled simpieinit to disti nguish itfrom the System V compati ble versi onsof ina that are starti ng to appear 
in theLinux community, simpieinit should belinked to, ormadeidentical with, init for correct functionality. 

AUTHOR 

Peter Orbaek (poe@daimi.aau.dk), version 1.20, with patchesfor single-user modeby Werner Almesberger. 

Linux 0.99, 20 N ovember 1993 

slattach 

siattach— Attach a network interface to a serial line. 
SYNOPSIS 

slattach [-v] [ - p proto] [ - s s p e e d ] [tty] 

D ESC RIPTIO N 

slattach is a I itti e program that can beused to put a normal terminal ("serial") lineinto oneof several "network" modes, 
thusallowingyou to use it for point-to-point links to other computers. 

0PTI0NS 

[-v] E nable debugging output. U seful when determi ni ngwhy agi ven setup doesn't work. 

I-p proto ] Set a speci fi c kind of protocol to useon the li ne. The default i s set to eslip, compressed 

SLIP. Other possible values are slip (normal SLIP), ppp (Point-to-Point Protocol), and 

kìss(AX.25TNC protocol). 
I-s speed] Set a specific line speed other than the default. 

If no arguments aregi ven, the current terminal line (usually the login device) isused. 

Otherwise, an attempt ismadeto dai m the indi cated terminal port, lock it, and open it. 

FILES 

/dev/cua* 

BUGS 

N oneso far. 

AUTHOR 

Fred N . van Kempen (waltje@uwalt.hl.rnugnet.org) 

20 September 1993 

sliplogin 

siipiogin— Attach a seri al line network interface. 
SYNOPSIS 

sliplogin [I ogi n ri a me ] 

DESCRIPTION 

siipiogin isused to turn the terminal lineon standard input into a serial li ne IP SLIP link to a remote host. To do this, the 
program searchesthefileforan entry matchingi ogi nname (which defaults to the current login nameif omitted). If a 
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matching entry isfound, the line is confi gured appropriately for slip (8-bit transparent I/O ) and converted to slip line 
discipline. Then ashell script isinvoked to i ni ti alize the slip interface with the appropriate locai and remote IP address, 
netmask, and so on. 

Theusual initialization script is /etc/siip/siip.igin, but if particular hosts need special initialization, thefile 
/etc/siip/siip.iogin.ioginname will beexecuted instead if itexists. The script isinvoked with theparameters 

siipunit The uni t number of the slip interface assi gned to thisline, such ase for sio. 

speed Thespeed of theline. 

args T he arguments from the entry, in order starti ng with i o g i n n a me . 

Only thesuperuser can attach a network interface. The interface isautomatically detached when theother end hangsup or 
thesiipiogin processdies. If the kernel slip modulehasbeen configured for it, ali routesthrough that interface will also 
disappear atthesametime. If thereisother processing a site wantsdoneupon hangup, thefile /etc/siip/siip.iogout or 
/etc/siip/siip.iogout.ioginname isexecuted if it exists. It isgiven the same arguments as the login script. 

FORMATOF/etC/slip. hOStS 

C omments (li nes starti ng with a#) and blank linesareignored. Other linesmust start with ai o g i n n a me , but the remai ni ng 
arguments can bewhatever is appropriate for the file that will beexecuted for that name. Arguments are separated by 
whitespaceand follow normal sh(l) quoti ngconventions(however, i o g i nname cannot bequoted). Usually, lineshavethe 

form o g i nname I oca! - address remote - address net mas k opt-args. local-address and remote - address are the IP hostnames Or 

addressesof the locai and remote endsof theslip line, and net mas k istheappropriatelP netmask. These arguments are passed 
directly to ifcontig(8). opt-args are optional arguments used to configure the line 

EXAMPLE 

The normal useof siipiogin isto create a entry foreach legai, remote slip site with siipiogin astheshell for that entry, 
such as 

Sfoo:ikhuy6:2010:1 :slip line to foo: /tmp: /usr/sbin/sliplogin . 

(Our convention isto name the account used by remote host hostnameasshostname.) Then an entry isadded that lookslike 

Sf oo 'host n a me ' foo n et ma s k 

' host name' will beevaluated by sh to thelocal hostnameand net ma s k isthelocal host IP netmask. 

N otethat siipiogin must besetuid to root, and although it'snot asecurity noia moral defedi ves can useitto place terminal 
li nes in an unusable state or deny access to I egiti mate usersof a remote slip line. To prevent this, a site can create a group, say 
slip, that only theslip login accounts are put i n and then makesurethat /sbin/siipiogin isin group slip and mode 4550 
(setuid root, only group slip can executebinary). 

DIAGNOSTICA 

siipiogin logsvarious informati on to the system log daemon, sysiogd(8), with a faci I ity codeof daemon. Themessagesare 
listed here, grouped by severity level. 

Error Severity 

iocti (tcgets) : reason A tcgets iocti to get the line parameters fai led. 

iocti (tcsets): reason A tcsets iocti to set the line parametersfailed. 

/etc/siip. hosts: reason T he file could not be opened. 

access denied for user N 0 entry for user was found in /etc/slip/slip. hosts 

Noti ce Severity 



"attaching slip unit" unit for U nit was successful ly attached. 

o g i n n a me SLIP unit 




SEEALSO 

slattach(8), syslogd(8) 

HI STORY 

Thesiipiogin command iscurrently in beta test. 

5 August 1991 

swapon, swapof f 

swapon, swapof f — E nable/disable devi ces and filesfor pagi ng and swapping. 
SYNOPSIS 

/sbin/swapon -a 
/sbin/swapon s pec i ai f i I e ... 
/sbin/swapoff -a 
/sbin/swapoff speci al fi I e ... 

D ESC RIPTIO N 

swapon isused to specify devi ces on which pagi ng and swappi ng are to take place. Calisto swapon usuai ly occur in the system 
multiuser initialization file /etc/rc making ali swap devices available, so that thepaging and swapping activity isinterleaved 
across several devices and files. 

Usually, the first form isused: 

-a Ali devices marked assw swap devices in /etc/fstab are made available. 

swapoff disables swapping on thespecified devices and files or on ali swap entriesin /etc/fstab when the -a flag isgiven. 

SEEALSO 

swapon(2), swapoff(2), fstab(5), init(8), mkswap(8), rc(8), mount(8) 

FILES 

/dev/hd[ab]? Standard paging devices 

/dev/sd[ab]? Standard (SC SI ) paging devices 

/etc/fstab ASCII filesystem description table 

HI STORY 

The swapon command appeared in 4.0 BSD . 
AUTHORS 

See the Linux mount(8) man page fora complete author list. Primary contri butors include Doug Quale, H.J. Lu, Rick 
Sladkey, and Stephen Tweedie. 

Linux 0.99, 27 Novemberl993 

sync 

sync— Flush Linux fi lesystem buffers. 
SYNOPSIS 

sync 
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DESCRIPTION 

sync executessync(2), which flushes thefilesystem buffersto disk, sync should becalled before the processor is halted in an 
unusual manner (before causing a kernel panie when debugging new kernel code). In general, the processor should be halted 
usingthereboot(8) omait(8) commands, which atterri ptto putthesystem in a quiescent state before calli ngsync(2). 

From Linus: "N otethat sync isonly guaranteed to schedule the di rty blocksforwriting: It can actually take a short time 
before ali the blocks are finally written. If you are doing the sync with theexpectation of ki lling the machine soon after, 
please take this into account and sleep for afew seconds. (Thereboot(8) command takestheseprecautions.)" 

SEEALSO 

sync(2), update(8), reboot(8), halt(8) 

AUTHOR 

LinUSTorvaldS (torvalds@cs.helsinki.fi) 

Linux 0.99, 20 N ovember 1993 



sysklogd 

syskiogd— Linux system logging Utilities. 
DESCRIPTION 

syskiogd providestwo system Utilities, which provide support for system logging and kernel messagetrapping. Support of 
both inetd and U N IX domain sockets enables this utility package to support both locai and remote logging. 

System logging is provided by a version of sysiogd derived from the stock BSD sources. Support for kernel logging is 
provided bythekiogd utility, which allows kernel logging to beconducted in either a stand-alone fashion orasaclient of 
sysiogd. 

Although the sysiogd sources h ave been heavily modified, a coupleof notes are in order. First of ali, therehasbeen a 
systematic atterri ptto ensurethat sysiogd follows standard BSD behavior asits default. The second important conceptto 
note isthat this version of sysiogd interaets transparently with theversion of sysiog found in the standard librari es. If a 
binary linked to the standard shared librariesfailsto function correctly, wewant an exampleof theanomalous behavior. 

CO NFIGU RATIO N FILE SYNTAX DIFFERENCES 

sysiogd uses a slightly different syntaxfor its confi guration fi le from that of the originai BSD sources. 0 riginally, ali messages 
of a specific priority and above were forwarded to the log fi le. 

For example, thefollowing linecaused ali output from thedaemon facilitiesto go into /usr/adm/daemons: 

# Sample sysiog. conf 

daemon. debug /usr/adm/daemons 

U nder the new scherme, this behavior remai ns the same. The differenceis the addi tion of two new wildeard speci fi ers: 
theasterisk (*) and theequalssign (=). The * specifies that ali messages for the indicated faci lity areto bedirected to the 
desti nati on. N otethat this behavior is degenerate with specifying a priority level of debug. Usersh ave indicated that the 
asterisk notation is more intuitive. 

T he = wildeard isused to restrict logging to the specified priority class. Thisallows, for example, routing only debug messages 
to a parti cui ar logging source 

For example, thefollowing line in sysiog. conf di reets debug messages from ali sources to the/usr/adm/debug file 



# Sample sysiog. conf 
daemon. =debug /usr/adm/debug 
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Thismay takesomeacclimatization for those individuai used to the pure BSD behavior, but testers haveindicated that this 
syntax issomewhat moreflexiblethan the BSD behavior. N otethatthesechangesshould not affect standard sysiog.conf 
files. You must specifically modify theconfiguration filesto obtain theenhanced behavior. 

SUPPORT FOR REMOTE LOGGING 

Thesemodifications provi de network support to thesysiogd facility. N etwork support meansthat messagescan beforwarded 
from onenoderunning sysiogd to another noderunning sysiogd wherethey will beactually logged to a disk file. 

Thestrategy isto have sysiogd li sten on aU N IX domain socketfor locally generated log messages. This behavior will allow 
sysiogd to intemperate with thesysiog found in the standard C library. Atthesametime, sysiogd listenson thestandard 
sysiog port for messages forwarded from other hosts. To have this work correctly, the services files (typically found in 
/usr/etc/inet) must havethefollowing entry: 

sysiog 514/udp 

To cause messages to beforwarded to another host, replace the normal filelinein thesysiog. conf filewith thenameof the 
hosttowhich the messages isto besent prepended with an §. 

For example, to forward ali messages to a remote host, usethefollowing sysiog.conf entry: 

# Sample sysiogd conf iguration file to 

# messages to a remote host forward ali. 
.* @hostname 

Toforward ali kernel messages to a remote host, theconfiguration fileis 

# Sample conf iguration file to forward ali kernel 

# messages to a remote host. 
kern.* @hostname 

OUTPUTTO NAMED PIPES(FIFOS) 

Thisversion of sysiogd has support for logging output to named pipes (FIFOs). A FIFO or named pipecan beused asa 
desti nati on for log messages by prependi ng a | to thenameof the fi le This ishandy for debugging. N ote that the FIFO must 
becreated with themkfifo command before sysiogd isstarted. 

Thefollowing configuration file routes debug messages from the kernel to a FIFO: 

# Sample configuration to route kernel debugging 

# messages ONLY to /usr/adm/debug which is a 

# named pipe. 

kern.=debug ] /usr/adm/debug 

INSTALLATA CONCERNS 

Thereisprobably oneimportant considerati on when i nstal li ng thisversion of sysiogd. Thisversion of sysiogd isdependent 
on proper formatti ngof messages by thesysiog functi on. T he functioningof thesysiog function in theshared libraries 
changed somewherein theregion of iibc.so.4.[2-4] .n. Thespecific changewasto nul I-termi nate the message before 
transmitting itto the /dev/iog socket. Proper functioningof thisversion of sysiogd isdependent on nul I-termi nati on of the 
message. 

This problem will typically manifest itself if old statically linked binariesare being used on the system. Binaries using old 
versionsof thesysiog function will cause empty linesto be logged, followed by the message with the fi rst character in the 
message remo ved. Relinking these binari esto newer versionsof theshared libraries will correct this problem. 

SECURITYTHREATS 

There is the potential for thesysiogd daemon to beused asa conduitfor adenial of servi ce attack. Thanksgo tojohn 
M orrison (jmorriso@rfiab.ee. ubc.ca) for alerti ng meto this potential. A rogueprogrammer could very easily flood the 
sysiogd daemon with sysiog messages resulti ng in the log files consumi ng ali the remai ni ng space on thefilesystem. 
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Activating logging over the inet domain sockets will of course expose a system to risksoutsideof programsor individualson 
the locai machine. 

Version 1.2 of the utility set will addressthis problem. In themeantime, therearea number of methodsfor protecting a 
machine: 

1. Logging can bedirected to an isolated ornon-rootfilesystem, which, if filled, will notimpair the machine 

2. Theext2 filesystem can beused, which can beconfigured to limita certain percentageof afilesystem to usageby root 
only. N otethatthiswill requiresysiogd to berun asa non-root process. Al so note thatthis will prevent usageof remote 
logging because sysiogd will beunableto bind to the514/U D P socket. 

3. D isabling inet domain sockets will limit risk to the locai machine. 

4. UseStep 3 and if the problem persistsand isnot secondary to a rogue program or daemon, get a 3.5 foot (approximately 
1 meter) length of sucker rad and havea chat with the user in questi on. A sucker rad i s 3/4-, 7/8-, or 1-inch hardened 
steel rad, malethreaded on each end. Itsprimary use in theoil industry in Western N orth Dakota and other locationsis 
to pump-suck oil from oil wells. Secondary usesarefortheconstruction of catti e feed lotsand for deal ing with the 
occasionai recalcitrant or beli igerent individuai. 

FILES 

/etc/syslog.conf 

BUGS 

Primarily, security concernswill beaddressed in version 1.2. 
SEEALSO 

klogd(l) 

COLLABORATO RS 

D r. G reg W ettStein (greg%wind. uucp@plains.nodak.edu) 

Enjellic Systems D evelopment 

0 n col ogy Research Division Computing Facility 

Roger M arisCancer Center 

Fargo, N D 

Stephen Tweedie 

D epartment of C omputer Science 

Edinburgh U niversity, Scoti and 

Juha Virtanen 

(jiivee@hut.fi) 

ShaneAlderton 

(shane@scs.apana.org.au) 

Version 1.1, 28 January 1994 

sysiogd 

sysiogd— Log systems messages. 
SYNOPSIS 

sysiogd [-f configgile] [ - m ma rk_i ntervai ] [-plogsocket] 

DESCRIPTION 

sysiogd readsand logs messages to the system console, logfiles, and other machinesor usersasspecified by itsconfiguration 
file. The options are asfollows: 
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-f Specify thepathnameof an alternate co nfigu rati on file the default is/etc/sysiog.conf. 

-m Select thenumber of minutesbetween "mark" messages; the default is 20 minutes. 

-p Specify thepathnameof an alternate log socket; the default is/dev/iog. 

sysiogd reads its configuration filewhen it startsup and whenever it receivesa hangup signal. For information on theformat 
of theconfiguration file, seesysiog.conf(5). 

sysiogd reads messages from theU N IX domain socket /dev/iog, from an Internet domain socket specified in /etc/services, 
and from the special device /dev/kiog (to read kernel messages). 

sysiogd createsthefile /var/run/sysiog.pid and stores itsprocessID there. Thiscan beused to kill or reconfigure sysiogd. 

Themessagesent to sysiogd should consist of a single line. Themessagecan contain a priority code, which should bea 
precedi ng decimai number in angle braces, such as<5>. This priority code should map into the priorities defi ned in the 

includefile <sys/syslog . h>. 

FILES 

/etc/sysiog.conf Theconfi guration file 

/var/run/syslog.pid TheprOCeSSlD Of Current sysiogd 

/dev/iog N ameof theU N IX domain datagram log socket 

/dev/kiog Thekernel log devi ce 

SEEALSO 

logger(l), syslog(3), services(5), syslog.conf(5) 

HI STORY 

The sysiogd command appeared in BSD 4.3. 

BSD 4.2, 16 March 1991 
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taikd— Remote user communication server. 
SYNOPSIS 

talkd 

D ESC RIPTIO N 

taikd is the server that notifies a user that someoneelse wants to initiate a conversati on. It actsa reposi tory of invi tati ons, 
responding to requests by clientswho wantto rendezvousto hold a con versati on. In normal operation, a client, the Caller, 
ini ti atesa rendezvous by sending acn msg to the server of type look up (see protocois/taikd.h). This causes the server to 
search its invitation tablesto check if an invi tati on currently exists for the Caller (to speak to th e cai I ee speci fi ed in the 
message). If thelookup fails, the Caller then sendsan announce message, causi ng the server to broadcast an announcement on 
the callee's logi n ports requesti ng contact. When the callee responds, the locai server usestherecorded invitation to respond 
with the appropriate rendezvous address and thecaller and callee client programs establish astream connection through 
which the conversation takes place. 

SEEALSO 



talk(l), write(l) 
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HISTORY 

Thetaikd command appeared in BSD 4.3. 

BSD 4.3, 16 M arch 1991 

telnetd 

teinetd— DARPA Telnet protocol server. 
SYNOPSIS 

/etc/telnetd [-debug [port]] [ -1] [ -D opt i ons ] [ -D r epor t ] 
[ -D e x e r ci s e ] [ -D net dat a ] [ -D ptydat a ] 

D ESC RIPTIO N 

telnetd isaserver thatsupportstheDARPA standard Telnet vi rtual terminal protocol, teinetd isinvoked by thelnternet 
server (seeinetd(8)), usually for requeststo connect to the Telnet port asindicated by the/etc/services file (see 
services(5)). If desired the -debug can beused, to start up telnetd manually, instead of through inetd(8). If started up this 
way, port may bespecified to run telnetd on an alternateTCP portnumber. 

The -d option can beused for debugging purposes. This ali ows Tel netto print debugging information to the connection, 
allowi ng the user to seewhat telnetd isdoing. T here are several modifiers: opti ons prints information aboutthenegotiation 
of Telnet opti ons, report prints the options information, plus some additional information aboutwhat processing isgoing 
on, net dat a displays the data stream received by telnetd, ptydat a di spi ays data w ri tten to thepty, and exercise hasnot been 
implemented yet. 

telnetd operates by allocati ng a pseudo-terminal device (see pty(4)) for aclient) and then creati ng a login processthat hasthe 
slave side of the pseudo-terminal asstdin, stdout, and stderr. telnetd manipulates the master side of the pseudo-terminal, 
i m pi ementi ng the Telnet protocol and passi ngcharacters between the remote eli ent and the login process. 

When a Tel net session is started, telnetd sends Telnet options to theclient side, indicatingawillingnessto do a remote echo 

Of Characters, tO suppress go ahead, tO do remote flOW control, and tO reca ve terminal type information, terminal Speed 

information, and window size information from the remote eli ent. If the remote ci ient iswilling, the remote terminal type is 
propagated in theenvironment of thecreated login process. The pseudo-terminal allocated to theclient isconfigured to 
operate in cooked mode and with xtabs and crmod enabled (seetty(4)). 

telnetd iswillingto do echo, binary, suppress go ahead, and timing mark. telnetd iswillingto have the remote ci ient 

do linemode, binary, terminal type, terminal speed, window size, toggle flOW control, environment, X display location, and 
suppress go ahead. 

If thefile /etc/issue.net ispresent, telnetd will show itscontents before the login prompt of a Telnet session (see 

issue . net(5)). 

SEEALSO 

telnet(l), issue. net(5) 

BUGS 

SomeTelnet commands are only parti ally implemented. 

Becauseof bugsin the originai 4.2 BSD teinet(l), telnetd performs some dubious protocol exchangesto try to discover if 
the remote client is, in fact, a4.2 BSD teinet(l). 

Binary modehasno common interpretation except between si mi lar operati ng systems(U N IX, in this case). 



ti med 




The terminal typenamereceived from the remote client isconverted to lowercase. teinetd never sendsTelnet go ahead 
commands. 

20 Aprii 1991 
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tftpd— D ARPA Trivial Fi le Transfer Protocol server. 
SYNOPSIS 

tftpd [directory ...] 

DESCRIPTION 

tftpd is a server thatsupports the D ARPA Trivial Fi le Transfer Protocol. TheT FTP server operatesattheport indicated in 
thetftp servicedescription; seeservices(5). The server isusually started by inetd(8). 

Theuseof tftp(l) doesnot requirean account or password on the remote system. Dueto thelack of authentication 
information, tftpd will allow only pubi icly readable fi lesto beaccessed. Filesmay bewritten only if they already exist and are 
pubi icly writable. N otethatthisextendstheconceptof publicto includeall userson ali hoststhatcan bereached through 
the network; thismay not be appropriate on ali systems, and its i mplications should beconsidered before enabling thetftp 
servi ce. The server should have the user ID with thelowest possi blepri vi lege. 

SEEALSO 

tftp(l), inetd(8) 

HI STORY 

The tftpd command appeared in BSD 4.2. 

BSD 4.2, 13 May 1991 
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tirned— Ti me server daemon. 
SYNOPSIS 

timed [-M] [-t] [-d] [-i network] [-n network] [-F hostl h o s 1 2 ...] 



DESCRIPTION 

timed is a ti me server daemon and isusually invoked at boottimefrom therc(8) file. It synchronizesthehost'stimewith the 
timeof other machine in a locai area network runningtimed(8). Thesetimeserverswill slow down theclocksof some 
machinesand speed up theclocks of othersto bringthem to the average network ti me. T he average network timeis 
computed from measurementsof clock differencesusingthelCM P timestamp request message. 

The servi ce provi ded by timed isbased on a master-slave scheme. When timed(8) is started on a machine, it asks the master 
for the network ti me and sets the host's clock to thattime. After that, it acceptssynchronization messages periodically sent by 
the master and callsadjtime(2) to perform theneeded correctionson the host's clock. 

It also communicateswith date(l) to set the date globally and with timedc(8), atimed control program. If themachine 
running the master crashes, then theslaveselect a new master from amongslavesrunningwith the -m flag. A timed running 
withoutthe -m or -Fflagsremainsaslave. The -t flag enables timed to tracethe messages it receivesin thefile 
/var/iog/timed.iog.Tracingcan beturned on or off by the program timedc(8). The -d flag isfor debugging the daemon. 
It causes the program to not put itself into the background. Usuai ly, timed checksfor a master ti me server on each network 
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to which it isconnected, except as modified by the opti ons. It requestssynchronization servicefrom the first master server 
located. If permitted by the -u flag, it provi dessyn eh ronization servi ce on any attached networkson which no current master 
server isdetected. Such a server propagatesthetimecomputed by the top-leve! master. The -n flag, followed by thenameof 
a network that the host isconnected to (seenetworks(5)), overrides the default choiceof the network addresses made by the 
program. Each ti me the -n flag appears, that network nameisadded to a list of valid networks. Ali other networksare 
ignored. The -i flag, followed by thenameof a network to which the host isconnected (see networks(5)), overrides the 
default choiceof the network addresses made by the program. Each ti me the -i flag appears, that network nameisadded to a 
list of networks to ignore. Ali other networks are used by thetimedaemon.The -n and -i flags are meani ngless if used 
together. 

timed checksfor a master ti me server on each network to which it isconnected, except as modified by the -n and -i options. 
If itfinds masterson morethan one network, it chooses one network on which to bea "slave" and then periodi rally checks 
the other networks to see if the masters there have disappeared. 

Oneway to synchronizea group of machinesisto usean NTP daemon to synchronizethe clock of one machine to a distant 
standard or a radio receiver and -F hostnameto teli itsumed daemon to trust only itself. 

M essages printed by the kernel on the system console occurwith interruptsdisabled. T hi smeans that the clock stopswhile 
they areprinting. A machine with many disk or network hardware problems and consequent messages cannot keep good 
timeby itself. Each messagetypically causes the clock to loseadozen milliseconds. A ti me daemon can correct the result. 

M essages in the system logabout machines that fai led to respond usuai ly indicate machines that crashed or wereturned off. 
Compiai ntsabout machines that fai led to respond to initial ti m e setti n gs are of ten associated with "multi-homed" machines 
that looked forti me masterson morethan one network and eventually choseto becomeaslaveon the other network. 

WARNING 

If two or moretimedaemons, whether timed, NTP, try to adjust the same clock, temporal chaoswill result. If both thisand 
another ti me daemon arerun on the same machine, ensure that the -f flag isused, so that timed never attemptsto adjust the 
locai clock. 

Theprotocol isbased on U D P/IP broadcasts. Ali machines within the rangeof a broadcast that are usingtheTSP protocol 
must cooperate. There cannot be morethan a single admi n i strati ve domain usi ng the -f flag amongall machines reached by 
a broadcast packet. Fai Iure to follow this rule is usuai ly indicated by compi ai nts concerni ng "untrusted" machines in the 
system log. 

FILES 

/var/iog/timed.iog traci ng file for timed 
/var/iog/timed. master-log log file for master timed 

SEEALSO 

date(l), adjtime(2), gettimeofday(2), icmp(4), timedc(8), "TSP: TheTimeSynchronization Protocol forU N IX 4.3 BSD," 
R.Gusella, S. Z atti . 

HI STORY 

The timed daemon appeared in BSD 4.3. 

BSD 4.3, 11 May 1993 

timede 

timede— Timed control program. 
SYNOPSIS 

timede [comma nd] [argument ...] 



traceroute 
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DESCRIVO N 

timedc isused to control theoperation of theamed(8) program. It may beused to 
M easurethedifferences between machines' clocks 
Find the location wh ere the master ti me server isrunning 
Enableor disable traci ng of messages received by timed 
Perform vari ous debugging actions 

Without any arguments, timedc will promptfor commandsfrom the standard input. Ifarguments are supplì ed, timedc 

i nterprets the fi rst argument as a command and the remai ni ng arguments as parameters to the command. The standard i nput 

may be redi rected, causing timedc to read commandsfrom afile. Commandsmay be abbrevi ated; recognized commandsare 

? [command ...] 

heip [command ...] Print a short descri ption of each command specified i n the argument list or, if no 

arguments aregiven, a list of the recognized commands. 

ciockdiff host ... Computethedifferencesbetweentheclockofthehostmachineandtheclocksofthe 

m ach i n es gi ven as argu m ents. 
msite [host ...] Show the master time server for specified hosts. 

trace {on | off} Enableor disablethetracing of incoming messagesto timed in thefile. 

eiection host Asks the daemon on the target host to reset its "election" timersand to ensurethat a 

ti me master hasbeen elected. 

quit Exit frolli timedc 

Other commands may beincluded for use in testi ng and debugging timed; thehelp command and the program sourcemay 
beconsulted fordetails. 

FILES 

/var/iog/timed.iog tracing filefor timed 
/var/iog/timed.masteriog log file for master timed 

SEEALSO 

date(l), adjtime(2), icmp(4), timed(8), "TSP: TheTimeSynchronization Protocol forti N IX 4.3 BSD," R. Gusella, S. Zatti. 
DIAGNOSTICS 

?Ambiguous command Abbreviation matches more than one command 

?Invalid command N 0 match found 

?priviieged command C ommand can be executed by root only 

HI STORY 

The timedc command appeared in BSD 4.3. 

BSD 4.3, 11 May 1993 

traceroute 

traceroute— Print the route that packets take to the network host. 
SYNOPSIS 



traceroute [ -m ma x _ 1 1 1 ] [ -n] [ -p por t ] [-q nqueries] 

[-r] [-s src addr ] [-t tos] [-w wa itti me ] host [packetsize] 
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DESCRIPTION 

The Internet isa largeand complex aggregation of network hardware, connected together by gateways. Tracking theroute 
one's packets follow (or finding the miscreant gateway that's di scardi ngyour packets) can bedifficult. traceroute utilizesthe 
IP protocol time-to-live field and attemptsto elicitan icmp time_exceeded responsefrom each gateway along the path to 
somehost. 

Theonly mandatory parameter is the desti nati on hostnameor IP number. The default probe datagram length i s 38 bytes, 
butthiscan beincreased by specifying a packet size (in bytes) after the desti nation hostname. 

Other optionsare 

-m ma x 1 1 1 Set the max ti me-to-live (max number of hops) used in outgoing probe packets. The 

default i s 30 hops (the same default used forTCP connections). 

-n Print hop addresses numerically rather than symbolically and numerically (savesa 

nameserver address-to-name lookup for each gateway found on the path). 

-p p o r t Set the base U D P port number used in probes (default ÌS33434). traceroute hopesthat 

nothing islisteningon U D P portsbaseto base + nhops-1 at the desti nation host(so an 
icmp portjjnreachable messagewill be returned to termi nate the route traci ng). If 
something islistening on a port in the default range, thisoption can beused to pick an 
unused port range 

-q nqueries Set the number of probes per tti to nquer i es (default isthree probes). 

-r Bypass the normal routingtablesand send directly to a hoston an attached network. If 

thehost isnoton a directly attached network, an errori s returned. Thisoption can be 
used to ping a locai host through an interface that hasno route through it (for example, 
after the interface was dropped by routed(8)). 

-s s r c _ a d d r Usethefollowing I P address(which mustbegiven asan IP number, not a hostname) as 

the source address i n outgoi ng probe packets. 0 n hosts with more than one I P address, 
thisoption can beused to force the source address to be something other than the IP 
address of the interface the probe packet is sent on. If the I P address is not one of this 
machine's interface addresses, an errar is returned and nothing issent. 

-t tos Set thetype-of-service in probe packets to thefollowing value (default zero). The value 

must bea decimai integer in the range 0 to 255. Thisoption can beused to seeif 
different types of serviceresult in different paths. (If you arenot runninga BSD 4.3 
tahoeor later system, thismay beacademic because the normal network servicessuch as 
Telnet and FTP don't letyou control the TOS). N ot ali valuesof TOS are legai or 
meaningful; seethelP specfordefinitions. Useful valuesareprobably (iow deiay) and 

(high throughput). 

-v Verbose output. Received ICM P packets other than time_exceeded and unreachables are 

listed. 

-w Set the ti me (in seconds) to waitfor a responseto a probe (default is 3 seconds). 

This program attemptsto trace the route an IP packet would follow to some Internet host by launching U D P probe packets 
with asmall tti (timeto live) andthen listeningforan ICMP "timeexceeded" replyfrom agateway. W e start our probes 
with atti of one and increaseby one unti I weget an ICM P "port unreachable" (which meanswe gotto "host") or hit a max 
(which defaultsto 30 hops and can bechanged with the -m flag). Three probes (changed with the -q flag) are sent at each tti 
setti ng and a lineisprinted showingthetti, address of the gateway, and round-trip timeof each probe. If the probe answers 
comefrom different gateways, the address of each responding system will beprinted. If thereis no responsewithin a three 
second time-out interval (changed with the -w flag), a * isprinted forthat probe. 

Wedon't want the desti nation host to processtheU D P probe packets, so the desti nation port isset to an uni ikely value (if 
someclod on the desti nation is usi ng that value it can bechanged with the -p flag). 
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A sampleuseand output might be 

[yak 71]% traceroute nis.nsf.net. 
traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 
56 byte packet 

1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 

5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 

6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 

7 131.119.2.5(131.119.2.5) 59 ms 59 ms 59 ms 

8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 

9 129.140.71.6(129.140.71.6) 139 ms 239 ms 319 ms 

10 129.140.81.7(129.140.81.7) 220 ms 199 ms 199 ms 

11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 

N otethat Lines 2 and 3 arethesame. Thisisdueto a buggy kernel on thesecond hop system— ibi -csam. arpa— that 
forwards packetswith azero tti (a bug in the distributed version of 4.3 BSD). N otethatyou haveto guesswhat path the 
packets aretaking cross-country becausetheN SFN et (129.140) doesn't supply address-to-name trans! ationsfor its N SSs. 

A more interesting example is 

[yak 72]% traceroute allspice.lcs.mit.edu. 

traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max 

1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 

5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 

6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 

7 131.119.2.5(131.119.2.5) 59 ms 59 ms 39 ms 

8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms 

9 129.140.71.6(129.140.71.6) 139 ms 139 ms 159 ms 

10 129.140.81.7(129.140.81.7) 199 ms 180 ms 300 ms 

11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 
-| 2 * * * 

13 128.121.54.72(128.121.54.72) 259 ms 499 ms 279 ms 

-| 4 * * * 

15 * * * 

16 * * * 

17 * * * 

18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 

N otethat the gateways 12, 14, 15, 16, and 17 hop away. Either don't send ICM P "timeexceeded" messagesor send them 
with atti too anali to reach us Lines 14- 17 arerunning theM IT C Gateway code that doesn't send "timeexceeded"s God 
onlyknowswhat'sgoingonwith 12. 

Thesilent gateway 12 may betheresult of a bug in the 4. [23] BSD network code (and its derivati ves): 4.x (x <=3) sendsan 
unreachablemessageusingwhatevertti remainsin theoriginal datagram. Becausefor gateways the remainingtti iszero, the 
IC M P "timeexceeded" isguaranteed to not makeit back to us. Thebehavior of thisbug isslightly moreinterestingwhen it 
appears on thedestination system: 

1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 

5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 

6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 

7 *** 

8 *** 



ms 
ms 

39 ms 
39 ms 
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10 * * * 
1 -i * * * 

1 2 * * * 



13 nip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms 
] 

N oti ce that there are 12 "gateways" (13 is the final desti nation) and exactly thelast half of them are "missing." What's really 
happening isthat rip (aSun-3 runningSun OS3.5) isusing thetti from our arrivi ng datagram asthetti in itsICM P reply. 
Thereply will timeout on the return path (with no noticesentto anyonebecauselCM Psaren't sent for ICM Ps) until we 
probe with atti that'sat least twicethe path length. That is, rip is really only seven hopsaway. A reply that returnswith a 
ttiof 1 isa cluethis problem exists. traceroute printsa ! after the ti me if the tti islessthan orequal to 1. B ecause ven do rs 
ship a lot of obsolete (D EC U Itrix, Sun 3.x) or non-standard H PUX software, expectto seethis problem frequently ortake 
care pi cking the target hostof your probes. Other possible annotations after thetimeare ih, in, ìp (gota host, network, or 
protocol unreachable), is, or if (sourceroutefailed orfragmentation needed— neither of theseshould ever occur and the 
associated gateway isbusted if you seeone). If almost ali the probes result in somekind of unreachable, traceroute will give 
up and exit. 

Thisprogram isintended forusein network testi ng, measurement, and management. Itshould beused primarilyformanual 
fault isolation. Becauseof theload it could impose on the network, it isunwiseto use traceroute during normal operati ons 
or from automated scripts. 

AUTHOR 

Implemented by Van Jacobson from asuggestion by Steve Deering. Debugged by acastof thousandswith particularly 
cogent suggestionsorfixesfrom C. Philip Wood, Tim Seaver, and Ken Adelman. 

SEEALSO 

netstat(l), ping(8) 

BSD 4.3, 6 Junel993 



tune2fs 

tune2fs— Adjusttunablefilesystem parameterson second extended filesystems. 
SYNOPSIS 

tune2fs [ -1 ] [ -c max - mount - c ou nt s ][-e errors-behavior ] 

[ -i i nt er vai • bet ween- c hec ks ][ -m reserved-blocks-percentage ] 

[ -r r e s e r v e d - bl oc ks- count ] [ -u user ] [ - g g r o li p Jdevice 

D ESC RIPTIO N 

tune2ts adjusts tunable filesystem parameterson a Linux second extended filesystem. 
N ever use tune2fs on a read/writemounted filesystem to change parameters! 

OPTIONS 

-c max - mount - count s Adjust the maxi mal mounts count between two filesystem checks. 

-e errors- behavi or C hange the behavior of the kernel codewhen errorsaredetected. errors- behavi or can 

beoneof thefollowing: 

continue C ontinue normal execution. 

remount-ro Remount the filesystem read-only. 

panie Causes a kernel panie. 



tundp 



-g group Set the user group that can benefit from the reserved blocks. g r o up can bea numeri cai 

GID or a group name. 

-i i ntervai -between-checks [d|m>] Adjust the maxi mal timebetween two fi I esystem checks. No postfix or d resultsin days, 

m in months, and w in weeks. A valueof 0 wi 1 1 disablethetime-dependent checking. 
-1 List the contentsof the filesystem superblock. 

-m reserved- b i ocks-percentage Adjust the reserved blocks percentage on thegiven device, 
-r reserved - bi oc ks- count Adjust the reserved blocks counton thegiven device. 

-u user Set the user who can benefit from the reserved blocks. user can bea numerical UID or a 

username 

BUGS 

Wedidn't find any bugs. Perhapstherearebugs, but it'sunlikely. 
WARNING 

Usethisutilityatyourownrisk.You'remodifyingfil esystem s. 
AUTHOR 

tune2fs waswritten by Remy Card (card@masi.ibp.fr), thedeveloper and maintainer of theext2 filesystem. tune2fs 
usestheext2fs library written byTheodoreT'so (tytsoumit.edu). Thismanual page waswritten byChristian Kuhtz 
(chk@data-hh.Hanse.DE). Time-dependent checking wasadded by UweOhse (uwe9tirka.gun.de). 

AVAILABILITY 

tune2fs isavailablefor anonymOUS FTP from ftp.ibp.fr and tsx-11.mit.edu in /pub/linux/packages/ext2fs. 

SEEALSO 

durnpe2f s(8), e2fsck(8), mke2fs(8) 

Version 0.5b, N ovember 1994 



tunelp 



tuneip— Set various parameters for the Ip device. 
SYNOPSIS 

tunelp device [ - ± IRQ | -t TI HE | -c CHARS 

| -wWAIT | -a [onjoff] | -o [on|off] | -C [on]off] 

| -r ! -s | -q [onjoff] ] 

D ESC RIPTIO N 

tuneip setsseveral parameters for the /dev/ip? devices, for better performance (or for any performance at ali, if your printer 
won'twork without it... ). Without parameters, tunelp tei Iswhether the device is usi ng interrupts, and if so, which one. 
With parameters, tunelp sets the devi ce characteristi cs accordi ngly. Theparametersareasfollows: 

-i <i rq> The IRQ to use for the parai lei port in question. If this is set to something nonzero, -t 

and -c nave no effect. If your port doesnot use interrupts, thisoption will make 
printing stop, tunelp -i 0 restoresnon-interruptdriven (poli i ng) action, and your 
printer should work again. If your parai lei port does support interrupts, interrupt-driven 
printing should besomewhat faster and efficient and will probably bedesirable. 

-t <ti me > The amount of ti me in j iffies that the driver waits if the printer doesn't take a character 

forthenumber of triesdictated by the -c parameter. 10 is the default value. If you want 
the fastest possi ble printing and don't care about system load, you can set this to 0. If 
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you don't carehow fastyour printer goesor are printing text on aslow printer with a 
buffer, then 500 (5 seconds) snould be fine and will giveyou very low system load. This 
vai uegen erally snould belower for printing graphics than text, by afactor of approxi- 
mately 10, for best performance. 

-c <c hars > Thenumber of ti mesto try to output a characterto the printer beforesleepingfor 

-t <ti me >. It is thenumber of timesaround a loop that triesto send a characterto the 
printer. 120 appearsto beagood valuefor most printers. 250 is the default becausethere 
are some printers that requireawaitthislong, butfeel freeto changethis. If you havea 
very fast printer likean H P Laserjet 4, avalueof 10 might makemoresense. If you have 
a really old printer, you can increasethis. 
Setti ng -t <ti me> to 0 isequivalent to setting -c <chars > to infinity. 

-w <wait> Thebusy loop counter for the strobe signal. Although most printers appearto beableto 

deal with an extremely short strobe, someprintersdemand alongerone. Increasingthis 
from the default 0 might makeit possi bleto print with those printers. This can also 
makeit possibleto uselonger cables. 

■a [onjoff ] Thisiswhether to abort on printer error; the default isnot to. If you are sitti ng at your 

computer, you probably want to beableto seean error and fix it and have the printer go 
on printing. On the other hand, if you aren't, you might rather that your printer spooler 
find out that the printer isn't ready, quit trying, and send you mail about it. Thechoice 
isyours. 

-0 [on|off] Thisoption ismuch like -a. It makesany openo of thisdevicecheckto seethatthe 

device is online and not reporti ng any out-of-paper or other errors. This is the correct 
setting for most versi onsofipd. 

-c [onjoff ] Thisoption adds extra ("careful") error checking. When thisoption ison, the printer 

driver will ensure that the printer is online and not reporting any out-of-paper or other 
errors beforesending data. This is parti cularly useful for printers that usually appearto 
accept data when turned off. 

-s Thisoption returnsthecurrent printer status, both as a decimai number from 0 to 255 

and asalistof activeflags. When thisoption isspecified, -q off, turni ng off the display 
of thecurrent IRQ, isimplied. 

-0, -c, and -s ali requirea Linux kernel version of 1.1.76 orlater. 
-r Thisoption resetstheport. It requiresa Linux kernel version of 1.1.80 or later. 

-q [onjoff] This option sets printing the display of thecurrent IRQ setti ng. 

Coheave Systems 26 August 1992 



updatejtate 

update„state— U pdate system state. 
SYNOPSIS 

update_state 

D ESC RIPTIO N 

update_state updates a bunch of system states. Ittakesa longtimeto executeand would besuitablefor execution in acron 
job. 

Currently, update_state performsthefollowingfunctions: updates the locate database (in /usr/iib/iocate), updates the 

whatis database(in /usr/man, /usr/local/man, /usr/X386/man, and /usr/interviews/man), and updates theTeX ls-R Cache fi le 
(in /usr/lib/texmf). 



u uci co 




BUGS 

The script expeets things to bewherethe FSSTN D saysthey are. For example, if you havemakewhatis(8) in /usr/iib, where 
it i s traditi onally, then you lose, because it should be in /usr/bin. 

SEEALSO 

cron(8), f ind(l), locate(l) 

AUTHOR 

Rik Faith (faithgcs.unc.edu) 

Linux 1.0 8, July 1994 

uucico 

uucico— UUCP fi le transfer daemon. 
SYNOPSIS 

uucico [ opti o n s ] 

D ESC RIPTIO N 

The uucico daemon processes fi le transfer requests queued by uucp(l) and uux(l). It isstarted when uucp or uux isrun (unless 
they aregi ven the -r option). 1 1 i s al so typically started peri odically using entries in thecrontab tables. 

When invoked with -n, --master, -s, --system, or -s, thedaemon will place a cali to a remote system, running in master 
mode Otherwise, thedaemon will start in slave mode, accepting a cali from a remote system. Typically, a special login name 
will besetupforUUCP.which automatically invokes uucico when a cali ismade. 

When uucico terminates, it invokes the uuxqt(8) daemon, unless the -q or --nouuxqt option isgiven; uuxqt(8) executesany 
work orders created by uux(l) on a remote system and any work orders created locally that havereceived remote fi les for 
which they werewaiting. 

If a cali fails, uucico will usually refuse to retry the cali until acertain (configurable) amount of timehaspassed. Thismay be 
overridden bythe -f, -torce, or -s option. 

The -ì, --prompt, -e, or - -loop options may beused to force uucico to produce itsown promptsof login: and Password:. 
When another daemon cai Is in, it will seethesepromptsand log in as usuai. The login name and password are usually 
checked against a separate list kept specially for uucico rather than the/etc/passwd file; it is possi bleon somesystemsto 
direct uucico to use the /etc/passwd file. The -ìor - prompt option will prompt once and then exit; in thismode theUUCP 
administrator orthesuperuser may use the -u or - login option to force a login name in which case uucico will not prompt 
for one. The -e or -loop option will prompt again after the first sessi on isover; in thismode, uucico will permanently control 
a port. 

If uucico receivesasiGQuiT, sigterm, or sigpipe signal, itwill cleanly abort any current conversation with a remote system 
and exit. If it receives a sighup signal, itwill abort any current conversation, but will conti nueto place Calisto (if invoked 
with -n or - -master) and accept cai Is from (if invoked with -e or - -loop) other systems. If it receives a sigint signal, itwill 
finish thecurrent conversation but will not place or accept any more calls. 

OPTIONS 

Thefollowing options may begiven to uucico: 

-n, ---master Start in master mode(call outto asystem); implied by -s, --system, or -s. If no system 

isspecified, cali any system for which work iswaiting to bedone. 
-re, ---slave Start in slave mode. T his isthe default, 

-s system, ---system system Cali thenamed system. 
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■S system 
-f, - - -force 
-1, - - -prompt 



-p por t , - - -port p o r t 
-e, - - -loop 



-q. 

-c, 



-wait 



-nouuxqt 
-quiet 



-C, 
-D, 



-ifwork 
-nodetach 



-u name, - - -login name 



-try-next 



-i t y pe , - - -stdin t y p e 



•x t ype, -X t y pe, - - -debug t y pe 



-I file, - - -conf ig file 

-v, - - -version 
- -help 

-u login 



Cali thenamed system, ignori ng any required wait. This isequivalent to -s system -f. 
Ignoreany required wait for any systemsto be cali ed. 

Prompt for login name and password usi ng login: and Password i.Thisallows uucico to 
beeasily run from inetd(8). Thelogin nameand password arechecked against the 
UUCP password file, which probably hasno connection to thefile /etc/passwd. The 
--login option may beused to forcea login name, in which caseuucico will only 
prompt for a password. 
Specify a port to cali out on or to li sten to. 

Enter endless loop of login/ password promptsand slave mode daemon execution. The 
program will not stop by itself; you must use kiii(l) to shut it down. 
After cai I i ng out(to a particular system when -s, - -system, or -s isspecified orto ali 
systems that havework when just -n or - -master isspecified), begin an endless loop as 

With --loop. 

Do not start theuuxqt(8) daemon when finished. 

If no calls are permitted at this ti me, then don't make the cali, but also do not put an 
error message in the log file and do not update the system status (as reported by 
uustat(l)).Thiscan beconvenientforautomated poi ling seri pts, which may wantto 
simply atterri ptto cali every system ratherthan worryabout which particular systems 
may be called atthemoment. Thisoption also suppressesthelog message in di cating 
that there is no work to be done. 

Only cali thesystem named by -s, --system, or -s if there is work for that system. 
Do not detach from the controlling terminal. N ormally, uucico detachesfrom the 
terminal beforeeach cali outto another system and before invoking uuxqt. This option 
preventsthis. 

Set thelogin nameto useinstead of that of the invoking user. Thisoption may only be 

used bytheUUCP administratororthesuperuser. If usedwith -prompt, thiswill cause 

uucico to prompt only for the password, not the login name. 

If a cali fai Is after the remote system isreached, try the next alternate rather than simply 

exiting. 

Set the typeof port to use when usi ng standard input. The only support port type is 
T LI, and this is only availableon machinesthat support the T LI networking interface. 
Specifying -mi causes uucico to useTLI Calisto perform I/O. 
Turn on particular debugging types. The following types arerecognized: abnormai, chat, 

handshake, uuep-proto, proto, port, config, spooldir, execute, incoming, outgoing. 

M ultiple types may begiven, separated by commas, and the - -debug option may appear 
multipletimes. A number may also begiven, which will turn on that many types from 
theforegoing list; for example, --debug 2 isequivalent to --debug abnormai, chat. 
The debugging output is sent to the debugging file, usually oneof /usr/spooi/uucp/ Debug, 

/usr/spool/uucp/DEBUG, Or /usr/spool/uucp/ .Admin/audit .locai. 

Set configuration fileto use Thisoption may not be avai lable, depending on how 

uucico was compi led. 

Report version information and exit. 

Print a help message and exit. 

Thisoption isignored. It isonly included becausesomeversionsof uucpd invokeuucico 
with it. 



FILES 



Thefilenamesmay bechanged at compilation ti me or by the configuration file, so these are only approximations: 
/usr/iib/uucp/contig Configuration file, 

/usr/iib/uucp/passwd DefaultUUCP password file. 



vmstat 



F] 



/usr/spooi/uucp UUCP spool directory. 

/usr/spool/uucp/Log UUCP log file. 

/usr/spooi/uucppubiic Default UUCP public directory. 

/usr/spooi/uucp/Debug D ebuggi ng file. 

SEEALSO 

kill(l), uucp(l), uux(l), uustat(l), uuxqt(8) 

AUTHOR 

lan LanceTaylor (ian@airs.com) 

Taylor UUCP 1.05 



vmstat 

vmstat— Report virtual memory stati stics. 
SYNOPSIS 

vmstat [ -n ] [ del ay [ count ] ] 

DESCRIVO N 

vmstat reports information about processes, memory, paging, block IO, traps, and CPU activity. 

The first report produced givesaverages sirice the last reboot. Additi onal reports gi ve information on a sampling peri od of 
length delay. Theprocess and memory reports are i nstantaneous in either case. 

OPTIONS 

The -n switch causestheheaderto bedisplayed only onceratherthan periodi cally. 

delay is the delay between updatesin seconds. If no delay isspecified, only one report is printed with theaveragevaluessince 
boot. 

count isthenumberof updates. If no count isspecified and del ay isdefined, count defaultsto infinity. 
FIELD DESCRIPTIONS 



Procs 

r Thenumberof processes waitingfor runtime 

b Thenumberof processes in uninterruptiblesleep. 

w The number of processes swapped out but otherwise runnable. 

Thisfield iscalculated, but Linux neverdesperation swaps. 

M emory 

swpd T he amountof virtual memory used (KB). 

tree T he amount of idle memory (K B). 

buff Theamountof memory used asbuffers(KB). 

Swap 

si Amountof memory swapped in from disk (KB/s). 

so Amountof memory swapped to disk (KB/s). 
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IO 



bi 


Blocks sent to a block devi ce(block^s). 


bo 


Blocks received from a block device (blocks/s). 


System 




in 


Thenumber of interrupts per second, includi ng the clock. 


cs 


The number of context switches per second. 


CPU (T hese are percentagcs of total CPU time.) 




US 


User time 


sy 


System time. 


id 


Idi e ti me. 



NOTES 

vmstat does not requi re special permissions. 

Thesereportsareintended to help i denti fy system botti enecks. Linux vmstat does not count itself asa running process. 
Ali Linux blocks are currently 1KB, exceptforCD-ROM blocks, which are2KB. 

FILES 

/proc/meminf o 

/proc/stat 

/proc/*/stat 

SEEALSO 

ps(l), top(l), free(l) 

BUGS 

vmstat does not tabulate the block 1 0 per device or count the number of system calls. 
AUTHOR 

Written by H enry Ware(aii72@yfn. ysu.edu) 

Throatwobbler Ginkgo Labs 27 J uly 1994 

vipw 

vipw— Edit the password file. 
SYNOPSIS 

vipw 

D ESC RIPTIO N 

vipw edits the password fi le after setti ng the appropriate locks and does any necessary processing after the password fileis 
unlocked. If the password fileisalready locked for editing by another user, vipw will ask you to try again later. The default 
editor for vipw isvi(l). 



zie 




ENVIRONMENT 

If thefollowing environment variable exists, itwill be utilizai by vipw: 

editor The editor specified by the stri ng. editor will beinvoked instead of the default editor 

vid). 

SEEALSO 

passwd(l), vi(l), passwd(5) 

HI STORY 

Thevipw command appeared in BSD 4.0. 
BSD 4, 16 M arch 1991 

zdump 

zdump— T i me zone dumper. 
SYNOPSIS 

zdump [ -v ][-c cut offyear ] [ z o ri e n a me ... ] 

D ESC RIPTIO N 

zdump printsthecurrenttimein each zonename named on the command line 
T hese options are available: 

-V 



-c cut of f year 

SEEALSO 

newctime(3), tzfile(5), zic(8) 

zie 

zie— T i me zone compi ler. 
SYNOPSIS 

zie [ -v ][-d directory ][-l localtime ][-p posi xrul es ] 
[-L leapsecondfilename ][-s ] [ -y command ] [ f i I e n a me ... ] 

DESCRIPTION 

zie reads text from thefiles named on the command line and createsthetimeconversion information fi les specified in this 
input. If afilenameis -, thestandard input isread. 

T hese options are available: 

-d di rectory C reate ti me conversi on information filesin the named directory ratherthan in the 

standard directory named below. 



For each zonename on thecommand line, printthecurrenttime, the ti me at thelowest 
possibletimevalue, the ti me one day after thelowest possibletimevalue, thetimes both 
onesecond beforeand exactly at each detected ti me disconti nuity, the ti me at one day 
lessthan the highest possibletimevalue, and the ti me at the highest possibletimevalue. 
Each line endswith isdst=i if thegiven time is D aylight Savi ngTime or isdst=e 
otherwise. 

C ut off the verbose output near the start of the gi ven year. 
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-i ti me zone Usethegiven ti me zone as locai ti me. zie will act as if the input contai ned a link line of 

theform. 

Link ti me z o n e I ocal ti me . 

-p ti mezone U se the gi ven ti mezone's rules when handling POSIX-formattimezoneenvironment 

variables. zie will act asif the input contai ned a link li ne of theform. 

Link ti me z o n e posi xrul es . 

-l i eapsecondf i i ename Read leap second information from thefilewith thegiven name. If thisoption isnot 

used, no leap second information appears in output files. 
-v C omplai n if a year that appears i n a data fi le is outsi de the range of years representable 

by time(2) values. 

-s Limittimevaluesstored in output fi lesto values that arethesamewhether they'retaken 

to be signed or unsigned. You can use thisoption to generate SVVS-compatiblefiles. 
-y command Use thegiven command ratherthan yearistype when checkingyeartypes. 

Input linesaremadeup of fields. Fieldsareseparated from oneanother by any number of whitespacecharacters. Leading 
and trailingwhitespaceon input lines isignored. An unquoted sharp character (#) in the input introducesacommentthat 
extendsto the end of the li ne the sharp character appears on. W hitespacecharactersand sharp characters may beenclosed in 
doublé quotes(") if they'reto beused as part of afield. Any li ne that isblank (after comment stripping) isignored. N on- 
blank lines are expected to beof oneof threetypes: rule lines, zone lines, and link lines. 

A rule li ne has theform 

Rule NAME FROM TO TYPE N ON AT 5AVE LETTER/S 

Forexample: 

Rule US 1967 1973 - Apr lastSun 2:00 1:00 D 

The fields that makeup a rule li ne are 

name G ivesthe (arbitrary) nameof the set of rules this rule is part of. 

from G ivesthe first year in which the rule applies. Any integer year can besupplied; the 

Gregorian calendar isassumed. The word minimum (oran abbreviation) meansthe 
minimum year representable as an integer. The word maximum (oran abbreviation) means 
the maximum year representable asan integer. Rules can describetimesthat arenot 
representable asti me values, with theunrepresentabletimes ignored; thisallows rules to 
be portableamong hostswith differing ti me value types. 

to Givesthefinal year in which the rule applies. In addition to minimum and maximum, 

the word oniy (oran abbreviation) may beused to repeat the value of the from fidd. 

type Givesthetypeof year in which the rule applies. If type is-, the rule applies in ali years 

between from and to inclusive. If type issomethingelse, then zie executes the command 

yearistype year t ype 

to check thetype of ayear. An exit status of zero istaken to mean that the year isof the 
given type; an exit status ofone istaken to mean that the year isnot of thegiven type. 
n Namesthemonth in which the rule takeseffect. M onth namesmay be abbrevi ated. 

on Givesthedayonwhichtheruletakeseffect. Recognized forms include 

5 Thefifth of themonth 

ìastsun ThelastSundayinthemonth 
ìastMon The lastMonday in themonth 

sun>=8 First Sundayon or after the eighth 

sun<=25 Last Sundayon orbeforethe25th 

N amesof daysof theweek may be abbrevi ated or spelled out in full. 

Note that there must beno spaceswithin theoN fidd. 



zie 



AT 



SAVE 



LETTER/S 



Givesthetimeof day atwhich the rule takes effect. Recognized formsinclude 

2 Timeinhours 

2:00 Timein hoursand minutes 

15 : 00 24-hour format ti me (for ti mes after noon) 

1 :28: 14 Timein hours, minutes, and seconds 

Any of theseformsmay befollowed by theletterw if thegiven timeis locai wall clock 
ti me, s if thegiven timeis locai standard ti me or u (or g or z) if thegiven timeis 
universal time; in theabsenceof an indicator, wall clock timeis assumed. 
Givestheamountof timeto beadded to locai standard timewhen the rule is in effect. 
Thisfield has the same format as the at field (although, of course, thew and s suffixes 
arenot used). 

Gives the vari ablepart (for example, thes orD in EST or EDT) of ti me- zone abbrevi a- 
tionsto beused when this rule is in effect. If thisfield is-, thevariablepart isnull. 



A zone li ne has the form 

Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] 

For example: 

Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 

Thefieldsthatmakeup azonelineare 

nahe Thenameof thetimezone Thisisthenameused in creati ng the ti me conversion 

information fi le for the zone. 

gmtoff Theamount of timeto add to GMT to get standard timein this zone. Thisfield has the 

same format as the at and save fieldsof rulelines; begin the field with a minussign if 

ti me must besubtracted from GMT. 
rules/save The name of the rules that apply i n the ti me zone or, alternately, an amountof timeto 

add to locai standard time If thisfield is-, standard timealwaysappliesin the ti me 

zone. 

format The format for ti mezone abbrevi ations in this ti me zone. The pai rof characters%s is 

used to show where the vari ablepart of the ti me-zone abbrevi ation goes. Alternately, a 
slash (/) separates standard and daylight abbrevi ations. 

unti l The ti me at which theGMT offset or the rules change for a location. It isspecified asa 

year, a month, a day, and atimeof day. If this isspecified, the ti me-zone information is 
generated from thegiven GMT offset and rule change until the ti me specified. 
Thenext line must bea conti nuation line this has the same form asa zone line except 
that the stri ng zone and the name are omitted becausethecontinuation linewill place 
information starti ng at the ti me speci fi ed as the unti l field in the previ ous li ne in the fi le 
used by the previ ous line. Conti nuation linesmay contai n an unti l field, just aszone 
li nes do, indicati ng that the next I ine is a further conti nuation. 

A link line has theform 

Link LI NK- FROM LI NK- TO 

For example: 

Link US/Eastern EST5EDT 

The li nk- from field should appear as the name field in some zone li ne; the li nk-to field isused asan alternate name for that 
zone. 



Except for continuation lines, lines may appear in any order in the input. 
L i nes i n the fi le that descri be leap seconds have the followi ng form: 



,22 Part V 1 1 1 : Admi ni strati on and P ri vi I eged Commands 

Leap Y E A R MONTH DAY HH: MM: SS CORR R/ 5 

Forexample: 

Leap 1974 Dee 31 23:59:60 + S 

TheYEAR, month, day, and hh: MM: ss fi elds tei I when the leap second happened. ThecoRR fi dd should be+ if asecond was 
added or - if asecond wasskipped. TheR/ s field should be(an abbreviation of) stationary if the leap second timegiven by 
the otherfields should beinterpreted asGMT or (an abbreviation of) Roiiing if the leap second timegiven by theother 
fi elds should beinterpreted as locai wall clock ti me 

NOTE 

Forareaswith morethan two typesof locai ti me, you may need to use locai standard ti me in theAT field of the earliest 
transition time'sruleto en su re th at the earliest tran si ti on timerecorded in thecompiled file is correct. 

FILE 

/usr/iocai/etc/zoneinfo standard directory used for created files. 
SEEALSO 

newctime(3), tzfile(5), zdump(8) 
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addjtimer, deljimer, init_timer 

addjiimer, deljiimer, initjtimer— M anage event timers. 

SYNOPSIS 

#include <asm/param.h> 
#include <linux/timer.h> 

extern void add_timer(struct timer_list * timer); 
extern int del_timer(struct timer_list * timer); 
extern inline void init_timer(struct timer_list * timer); 

D ESC RIPTIO N 

add_timer schedulesan event, adding it to a linked list of events maintained by the kernel. dei_timer deletesascheduled 
event. t i me r poi nts to a 

struct timer_list { 

struct timer_list *n e x t ; 

struct timer_list *prev; 

unsigned long exp r es ; 

unsigned long data; 

void (*f unct i on ) (unsigned long); 

>; 

init_timer sets next and prev to null. T his is requi red fortheargument of add_timer. expi r e s is the desi red duration of the 
timer in jiffies, wherethereareHz (typically 100) jiffiespersecond. When the timer expi res, fu noti on iscalled with data as 
itsargument. It isthe responsi bi li ty of function to delete the event. If thesamefunction is managing several timers, the 
argument can beused to distinguish which oneexpired. 

RETURN VALUE 

deitimer returnszero on error— if next or prev arenot null, but the timer wasnot found. dei_timer also sets expi res to the 
ti me remai ni ng before the timer expi res and sets next and prev to null. Thus, calli ngdei_timer followed immediately by 
add_timer isano-op provided a kernel tick doesnot occur between thetwo cai I s. 

AUTHOR 

LinusTorvalds 

Linux 1.2.8, 31 May 1995 



adjust_clock 

adjust_ciock— Adjustsstartup timecounter to tick in GMT. 



SYNOPSIS 

linux/kernel/sys.c 
void adjust_clock( ) ; 

DESCRIPTION 

This routine adjuststhestartup timeby adding the ti me zone informati on to it. The goal isto get thestartup timeticking in 
GMT time. 



NOTES 

This routine iscalled from settimeofday(2) when thetime-zoneinformation is first set. 
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AUTHOR 

TheodoreT'SO (tytso@mit.edu) 

SEEALSO 

settimeofday(2) 

Linux 0.99.10, 7 july 1993 



ctrl_alt_del 

ctn_ait_dei— Routesthekeyboard interrupt C trl+Alt+D el keysequence. 
SYNOPSIS 

linux/kernel/sys.c 
void ctrl_alt_del(void) ; 

DESCRIVO N 

Thissimple routine tests the variablecjj for atrue/falsecondition. If it istrue, a hard reset isdoneby the system. 
Otherwise, asignal sigint issentto theprocesswith theprocessID 1, usually a program called init. 

WARNINGS 

This routine is in interrupt mode. It cannot sync( > your system. D ata loss may occur. It is recommended that you configure 
your system to send asignal to init, whereyou can control theshutdown. 

NOTES 

Thedefault of thisfunction isto do hard resets immediately. 

AUTHOR 

LinusTorvalds 

SEEALSO 

reboot(2), reset_hard_now(9), sync(2) 

Linux 0.99.10, 6 July 1993 



filejable 

tiie_tabie— Detailed descri ption of the table and table entry. 
SYNOPSIS 

From#include <linux/fs.h> 

struct file { 
mode_t fjnode; 

dev_t f_rdev; /* needed for /dev/tty */ 

off_t fjos; 

unsigned short f_flags; 

unsigned short f_count; 

unsigned short freada; 

struct file *f_next, *f_prev; 

struct inode *f inode; 
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struct file_operations *f_op; 

>; 

From linux/fs/file_table.c 

struct file *first_file; 
int nr_files = 0; 

D ESC RIFTIO N 

Thefiletable isfundamentally importantto any U N IX system. It iswhereall open files (Linux includesclosed filesaswell) 
arestored and managed by the kernel. For Linux, you can hardly do anything without referencing it in someway. 

Linux stores its fi le table as a doublé circular linked list. Theroot pointer to the "head" of thi s list isfirst_fiie. Also, a count 
of how many entries are in thefiletable ismaintained, called nr_mes. U nder thisscheme, the fi le table for Linux could be 
aslargeasmemory could hold. U nfortunately, thiswould beunmanageablein most cases. Your computer would beinthe 
kernel most of thetimewhen processes are more important. To keep thisfrom happening, nrtiies istested against nr_file 
to limi t the number of file table entries. 

U N D ERSTAN D IN G TH E STRU CTU RE 0 F TH E FILE TABLE 

Thefiletable isorganized as a doublé circular linked list. Imagi ne a ci relè of peoplewith everyone faci ng the same direction. 
Each person isfacing so that onearm isin thecircleand theother arm is outside the circle. N ow, if each person put hisor 
her right hand on theshoulder of the person in front of him or herand if each person touched the person behind him or her 
with hisor her left hand. You haveformed two circlesof arms, one inside and theother outside. The right armsrepresent 
poi nters to the next entry (or person). T he left arms represent pointers to the previous entry (or person). 

THE FILE STRU CTU RE, A FILE TABLE ENTRY 

At first glance, a table entry looksquitesimple. An entry contai ns how afilewasopened, whattty device, a reference count, 
pointers to other entries, pointer to v-node(thevts i-node) filesystem-specific i-nodeinformation, and so on. 



f_mode After AN D ingwith o accmode, thisiswhat bitsO and 1 mean: 

00 N o permissionsneeded 

01 Read-permission 

10 W ri te- pernii ssion 

11 Read-write 

f_rdev It isused only with tty lines. It contai ns the major and minor numbersof thetty device. 

t_pos Thecurrent position in afile, if meaningful. 

f_tiags Storagefortheflagsfrom openo andtcntio 

f_count Reference counter 

t reada T his is a Boolean variablewhereTrue meansthat an actual read isneeded. 

t_next, f jrev Pointersto other entries 

f_inode Pointer to v-nodeand filesystem-specific i-nodeinformation 

f_op Pointerto a fi le's operati ons 

AUTHOR 



LinusTorvalds 
SEE ALSO 

insert_file_f ree(9), remove_f ile_f ree(9), put_last_f ree(9) grow_files(9), file_table_init(9), get_empty_filp(9) 

Linux 0.99.10, 11 July 1993 
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file_table_init 

fiie_tabie_init— Initializesthefiletablein the kernel. 
SYNOPSIS 

linux/f s/file_table.c unsigned long f ile_table_init ( 
unsigned long start , unsigned long end); 

DESCRIPTION 

This routine is called from kemei_starto in ìinux/init/main.c. It sets first fiie, a struct file pointer, to null. This is the 
head of thelinked list of open filesmaintained in the kernel, theinfamousfiletablein ali U N IXs. 

RETURN VALUE 

Returnsstart . 

NOTES 

Becausethis is part of the kernel's startup routine, it hastheoption to allocate memory, in kernel space, for itself. It does not 
need to do this and returnsthenew start of memory for the next ini ti al izing section. In this case, start isreturned unmodi- 
fied. 

AUTHOR 

LinusTorvalds 

Linux 0.99.10, 9 July 1993 



filesystems 

fiiesystems— Detailsthetableof confi gured filesystems 
SYNOPSIS 

linux/fs /file systems . c 
From#include <linux/fs.h> 
struct file system t y pe { 

struct superbi ock *(*read_super) (struct super block *, void *, int); 
char *name ; 
nt requi res dev ; 

}; 

DESCRIPTION 

Thissourcecodemakesa data structure cali fiie_systems[ ], which contai ns ali theconfigured filesystems for the kernel. It is 
used primarily in nnux/fs/ super, c for many of themounting of filesystems functions 

THEMEANINGS 

This first member, in struct f i i e.system.type, isafunction pointer to a routinethatwill read in the su per _bi ock. A 
super.bi ock generically meansan i-node or special place on thedevicewhere information about theoverall filesystem is 
stored. 

Thename isjust the stri ng representation of thenameof a specific filesystem, such asext2 orminix. 

The final member, i nt. requi res. dev, isa Boolean value. If it isTrue, then the filesystem requi res a block device For False, it 
is unclear what happens, but an unnamed device is used, such as proc and nf s. 
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AUTHOR 

LinusTorvalds 

Linux 0.99.10, 12 July 1993 



get_empty_f ilp 

get_empty_fiip— Fetchesan unreferenced entry from thefiletable. 
SYNOPSIS 

linux/f s/f ile table.c 

struct file *get_empty_f ilp(void) ; 

DESCRIPTION 

Thisroutine will seek out an entry that isnot being referenced by any processes. If none are found, then itwill add new 
entri esto thefiletable, minimum of nr_file entries. 

NOTES 

Dueto grow_fiieso, a whole page of entri es is created at onetime. Thismay makemorethan nr_file entries. Also when an 
unreferenced entry is found, it is moved to the "end" of thefiletable. Thisheuristic isused to speed up finding unreferenced 
entries. 

RETURN VALUE 

null— N o entri eswere found and thefiletable isfull. 
Returns a pointer to the entry in thefiletable. 

AUTHOR 

LinusTorvalds 

SEE ALSO 

grow_files(9) 

Linux 0.99.10, 12 July 1993 



growjiles 

grow_f iies— Adds entries to the file table. 
SYNOPSIS 

linux/f s/file table.c 
void grow_files(void) ; 

DESCRIPTION 

Thisfunction adds entries to thefiletable First, it allocatela pageof memory. 1 1 f i I Is the enti re pagewith entries, adding 
each to thefiletable. 



AUTHOR 

LinusTorvalds 
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SEEALSO 

insert_file_f ree(9), remove_f ile_f ree(9), put_last_f ree(9) 

Linux 0.99.10, 12 July 1993 



in_group_p 

in_group_p— Searchesgroup ID sfora match. 
SYNOPSIS 

linux/kernel/sys.c 

int in_group_p(gid_t grp); 

DESCRIPTION 

Searches supplementary group IDsand theeffectivegroup ID for a match with grp. 

RETURN VALUE 

ReturnsTrue (1) if found; otherwise, false (0). 

AUTHOR 

LinusTorvalds 

SEEALSO 

getgroups(2), getgid(2), getregid(2), setgid(2), setregid(2), setgroups(2) 

Linux 0.99. 10, 7 July 1993 



insert_f ile_f ree 

insert_f iie_f ree— Adds a fi le entry i nto the fi le table. 
SYNOPSIS 

linux /fs/file_table.c 

static void insert_f ile_f ree(struct file *f i I e ) ; 

DESCRIPTION 

Thisnightmareof poi nters adds f i le into the fi le table with theroot pointer atf 1 e. Thisis a building block of the fi le table 
management. 

AUTHOR 

LinusTorvalds 

SEEALSO 

file_table_init(9), remove_file_f ree(9), put_last_f ree(9) 

Sea f iie_tabie(9) for detai Is on the fi le table structure. 

Linux 0.99.10 
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kerneljnktime 

kerneijiktime— C onvert startup struct mktime into the number of seconds since 00:00:00 J anuary 1, 1970. 
SYNOPSIS 

linux /kernel/ mktime. c 

long kernel_mktime(struct mktime * t i me ) ; 

D ESC RIPTI0 N 

ThtS TOUti ne ÌS Called from time_init(void), linux/init/main.c. kerneljnktime () COnvertS struct mktime (initialized from 

CMOS) into an encoded long. 
C0NVERSI0N METH0D 

First an array, month[i2], iscreated, holding how many seconds have passed to reach a peculiar month for a leap year. N ext, 
itsubtracts70fromthecurrentyear, makingl970 the beginning year. Itismath magic after thispoint; please look yourself. 
If you know why it doesthis, then send e-mail (seenroff source). 

RETURN VALUE 

Returns the encoded ti me in a long. 

FILES 

linux/kernel/mktime.C homeof routine 

NOTES 

This routine is called only during startup of the kernel. 

H i stori cai ly, the value (encoded long) counts the number of seconds since the E poch, which occurred at 00:00:00 J anuary 1, 
1970, and is called Coordinated U ni versai Ti me (UTC). In older manuals, thisevent is called Greenwich M ean Time 
(GMT). 

WARNINGS 

kerneljnktime o doesn't check to seeif the year isgreater than 1969. Besureyour CM OS isset correctly. It iscustomary to 
set on-board clocksto GMT and let processeswho askforthetimeto convert itto locai ti me, if necessary. 

RESTRICTI0NS 

For kernel use only. 

AUTH0R 

LinusTorvalds 

Linux 0.99.10, 5 July 1993 

proc_sel 

procjjei— Select a process by a criterion. 
SYNOPSIS 

linux/kernel/sys.c 
#include <linux/resource. h> 

static int procj>el(struct task_struct *p , int which, int who); 
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DESCRIVO N 

Comparsa task p to supplied information orthecurrent task in someaspect of priority. If who iszero, thecomparison istask 
p and thecurrent task. Otherwise, who and *p are the supplied information for thecomparison. 

OPTIONS 

Valid valuesof uhi eh: 

prio_process ComparesprocessID numbers. There isan exception here. If who isnot zero and task p is 

thecurrent task, then True isalwaysreturned. 
prio_pgrp C ompares process group leader numbers. 

priojjser Compares user ID numbers. 

RETURN VALUE 

Returnstruth valuesfa, 1). 

AUTHOR 

LinusTorvalds 



SEEALSO 

sys_setpriority(2), sys_getpriority(2) 



Linux 0.99.10, 7 July 1993 



put_file_last 

put_fiie_iast— M ovesafileto the "end" of the file table. 
SYNOPSIS 

linux/f s/f ile table. c 

static void put_last_free(struct file *f i I e ) ; 

DESCRIVO N 

Thisfunction will removef i e from the fi le table and insert it again at the end. You can access by 

first_f ile->prev 

AUTHOR 

LinusTorvalds 

SEEALSO 

insert_f ile_f ree(9), remove_f ile_f ree(9) 

Linux 0.99.10, 11 July 1993 

remove_f ile_f ree 

remove„fiie_free— Remove a file table entry from thelinked list. 
SYNOPSIS 

linux/f s/file table. c 

static void remove_f ile_f ree(struct file *f i I e ) ; 
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DESCRIVO N 

Thisroutineremovesthefilefrom thetable. Thisisused mostly for moving afileto the "end" of the list. 

AUTHOR 

LinusTorvalds 

SEEALSO 

insert_file_f ree(9), put_file_last(9) 
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Symbols 



* (asterisk), bash special 

parameters, 15 
@ (atsign), bash special 

parameters, 15 
\ (backsiash), bash escape 

character, 14 
$ (dollar sign) 

bash special parameters, 15 

expansion, 19 

ftp command, 148 
! (exclamation point) 

bash special parameters, 15 

ftp command, 148 
! command (telnet), 512 
> (greaterthan sign), 

redirection operator, 21 
- (hyphen), bash special 

parameters, 15 
< (lessthan sign), redirection 

operator, 21 
| (pipeline), bash, 12 
#(pound sign) 

bash comments, 14 

bash special parameters, 15 
? (question mark) 

bash special parameters, 15 

ftp command, 152 
? command 

telnet, 512 

xauth, 591 
_ (underscore), bash special 

parameters, 15 
/ directory, 1236 
0, bash special parameter, 15 
8859-1 character set, 1064 
8859-2 character set, 1064 
8859-3 character set, 1064 
8859-4 character set, 1064 
8859-5 character set, 1065 
8859-6 character set, 1065 
8859-7 character set, 1065 
8859-8 character set, 1065 
8859-9 character set, 1065 
8859-10 character set, 1065 



A 



AbekasYUV bytes, converting 

to portable pixmaps, 731 
aborti ) function, 892 
abs( ) function, 892-893 
absolutevalues, 892-893 

fi oating- point numbers, 919 

long integers, 960-961 
accept, 740-741 
access, 741-742 

errors, 741 

restrictions, 741 

return value, 741 
access control 

files, changing permissions, 
61-62 

hosts_ access, 1133-1136 
diagnosti cs, 1136 
files, 1133, 1136 
operators, 1134 
patterns. 1133-1134 
remote usernamelookup, 

1134-1135 
rules, 1133 
shell commands, 1134 
wildcards, 1134 
languageextensions, 

1137-1139 
memory, 804-805 
NNTP sites, 1167-1168 
account (ftp command), 148 
acct, 742 

acos( ) function, 893 
acosh( ) function, 893-894 
arti ve, 1104-1105 
active-times, 1104-1105 
add ( cvs command), 96 
AD DAD D RESS environ- 

ment variatale, 529 
add timer, 1424 
addftinfo, 2 
addgroup, 1258-1259 
addmntent( ) function, 

935-936 



addresses 

Internet, manipulating, 
953-954 

mail addressing, 1244-1246 
abbrevi ations. 1245 
casesensitivity, 1245 
compati bility, 1245 
postmasters, 1246 
routing, 1245 

physical, accessing, 818 

sed,476 

virtual memory, remapping, 
805-806 
adduser, 1258-1259 
adduser.conf, 1105 
adjtimex, 742-743 
adjust_clock, 1424-1425 
admin (cvs command), 96 
advisory locks, open files 

(applying/removing), 757 
afmtodit, 2-4 

files, 3 

options, 3 

running, 3 
agetty, 1259-1262 

arguments, 1260 

bugs, 1261 

diagnostics, 1261 

files, 1261 

issueescapes, 1261 

options, 1260 
alarm, 744 

alarm clock, setting, 744 
alias (shell command), 35 
aliases, 23-24, 1106 

bugs, 1106 

printing, 35 

removi ng names, 45 
alloca function, 894 

bugs, 894 

return values, 894 
allocating memory, 894, 976 
al low-n u 1 1_ glob_ expansion 

variatale (bash), 17 
allow-send-events( ) action 
(xterm), 714 
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alphasort( ) function, 

1012-1013 
American Standard Codefor 

Information, see ASC 1 1 
Andrew Toolkit raster objects, 

converting to portable 

bitmaps, 10 
ANSI C, converting to 

Kernighan & Ritchie, 4 
ansi2knr, 4 

antialiasing portable anymaps, 

381-382 
anytopnm, 4 

append (ftp command), 148 
application resources, 

printing, 5 
applications(client), listing, 

669-670 
appres, 5 
ar, 5-7 

copying, 7 

modifiers, 7 

options, 6-7 
are cosines, 893 
are sines, 894-895 
are tangents, 896 

two variables, 896-897 
arch, 8 

archive, 1262-1263 
archives 

creating, 5-7 
extractingfrom, 5-7 
indexes (generating), 

437-438 
modifying, 5-7 
shell, creating, 484-487 
arguments 

concatenati ng, 37 
outputting, 36-37 
readingfrom standard input, 
586-587 
arithmetic 
evaluation 
bash, 34 

I et command, 39 
expansion, bash, 20 



functions 

awk, 168-169 

sn( ), 1020-1021 

si nh{ ), 1021 

sqrt( ), 1023 

tan( ), 1047-1048 

tanh( ), 1048 
performing on portable 
anymaps 382-383 
arp, 1263 

ARP cache, manipulating, 

1263 
arrays 

awk, 164 

linear searches, 975-976 
searching sorteci, 900-901 
sorting, 1000 

articles (news), seetin 

as, 8-9 

ASCII (American Standard 

Codefor Information), 1064 
character set, 1214-1216 
graphics, converting to 
portable graymap, 10 
ascii (ftp command), 148 
ascii manual page, 1214-1216 
asciitopgm, 10 
asctime, 984-986 
asctime( ) function, 910 
asin( ) function, 894-895 
errors, 895 
return value, 895 
asinh( ) function, 895 
assemblers, as, 8-9 
asserti ) function, 895-896 
asterisk (*), bash special 

parameters, 15 
atsign (§), bash special 

parameters, 15 
atan( ) function, 896 
atan2( ) function, 896-897 
atanh( ) function, 897 
Atari compressed Spectrum 

files, converting to portable 

pixmaps, 494 
Atari Degas PI 1 files, 

converting to portable 

pixmaps, 378 



Atari Degas PI 3 files, 
converting to portable 
bitmaps, 379 
Atari uncompressed Spectrum 
files, converting to portable 
pixmaps, 495-496 
atexit( ) function, 897-898 
errors, 898 
return value, 898 
atktopbm, 10 
atobm, 49-57 
options, 50 
atof( ) function, 898 
atoi( ) function, 898-899 
atol( ) function, 899 
attributes, file, 59 
authentication 
cidentd, 69-70 
Kerberos authentication, 
461 

pcnfsd, 1355-1356 
pppd, 1366-1367 
authority files (X), xauth 

utility, 587-592 
auto resumé variable (bash), 
18" 

AutoCAD slide files, convert- 
ing to portable pixmaps, 
490-491 
AUTOSUBSCRIBE environ- 

ment variable, 529 
AUTOUNSUBSCRIBE 

environment variable, 530 
awk 

actions, 165-166 
arithmetic functions, 

168-169 
control statements, 167 
fields, 163 
functions, 170 
GNU extensions, 171 
historical features supported 

by gawk, 172 
I/O statements, 167 
operators, 166-167 
patterns, 165-166 
printf statement, 167-168 
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program execution, 162-163 
regular expressions, 166 
sprintf( ) function, 167-168 
stri ng constants, 169-170 
string functions, 169 
timefunctions, 169 
variatile, 163-165 
arrays 164 
built-in, 163-164 
typing and conversi on, 
164-165 

B 



backslashes(\), basii escape 

character, 14 
badblocks, 1264 
banner, 1210 
bash 

aliases, 23-24 

arguments, 11 

arithmetic evaluation, 34 

blanks, 12 

bugs, 46 

command execution, 25 
comments, 14 
compound commands, 13 

case, 13 

list, 13 

while, 13 
control operators, 12 
environments, 25-26 
escape character, 14 
exit status, 26 
expansion, 18-21 

arithmetic, 20 

brace, 19 

command su bsti tuti on, 20 
history, 33-34 
parameter, 19-20 
pathname, 21 
processsubstitution, 20 
quote removal, 21 
tilde. 19 

word splitting, 21 
files, 46 
functions, 23 



history list, 32-33 
invocation, 45-46 
job control, 24-25 
lists, 12-13 
meta characters, 12 
names, 12 
options, 11 
parameters, 14-15 

positi onal, 14 

special, 14-15 
pipelines(|), 12 
prompting, 26 
quoti ng, 14 
readline, 27-32 

commands 29-32 

control I i ng key bindings 
27 

customizi ng, 27 
denoting keystrokes, 27 
macro defini ti ons 28 
parser di recti ves, 28-29 
variables, 28 
redirection, 21-23 

dupl i cati ng fi I e descri ptors 
23 

here-documents 22-23 
input, 22 

opening fi le descri ptors 23 
operators 21 
output, 22 

standard error output, 22 
standard output, 22 

reserved words, 12 

shell variables, 15-18 
allow- 

null_glob_expanson, 17 
auto_ resumé, 18 
BASH, 15 

BASH VERSION , 15 
cdable_vars 18 
CDPATH, 16 
command_ ori ented_ hi story, 

17 
ENV, 16 
EUID, 15 
FCEDIT, 17 
FIGN ORE, 17 



gl ob_ dot_ fi I en ames, 17 
histchars 17-18 
HISTCMD, 16 
H I ST FILE, 17 
H IST FI LESIZE, 17 
history control, 17 
HISTSIZE, 17 
HOM E, 16 

hostn ame_ compi eti on_f i I e, 
18 

HOSTTYPE, 16 
IFS, 16 

IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 

M AIL_WARN IN G, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_exit_on_failed_exec, 
1~8 

noci obber, 18 
noli nks, 18 
notify, 17 
OLDPWD, 15 
OPTARG, 16 
OPTERR, 17 
OPTIND, 16 
OSTYPE, 16 
PATH, 16 
PPID, 15 

PROM PT_COM M AN D, 

17 
PS1, 16 
PS2, 16 
PS3, 17 
PS4, 17 
PWD, 15 
RANDOM, 15 
REPLY, 15 
SECONDE, 15 
SH LVL, 15 
TMOUT, 17 
UID, 15 
signals 25 

simple commands, 12 
words, 12 
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BASH variatile (bash), 15 
BASH VERSION variable 

(basii), 15 
bcmp( ) function, 899-901 
bcopy( ) function, 900-901 
BD F fonts, generati ng, 

146-147 
bdflush, 744-745 
errors, 745 
return value, 745 
bdftopcf, 47 
befordight, 47-48 
beli (ftp command), 148 
belli ) action (xterm), 713 
bell-style variable (readline), 

28 

Bennet Yee face files, see face 
files 

Bentleyizing portable 

graymaps, 369 
Bessel functions, 959-960 

j0( ), 959 

jl( ), 959 

jn( ), 959 

y0( ), 959 

yl( ), 959 

yn( ), 959 
bg (shell command), 35 
bibliographic databases, 219 

fields, 219 

inverted indexes, 209-210 
searching, 210, 292-293 
biff, 48 

biff server, 1274-1275 
/bin directory, 1236 
binary (ftp command), 148 
binary dates/times, converting 

to ASCII, 909-911 
binary files, encoding/ 

decoding, 565-566 
binary streams, input/ output 

(getting), 926-927 
binary trees 

deleting items, 1056 
searching, 1056 
traversing, 1056 



bind, 35, 745-746 

errors, 745-746 
return value, 745 
binding namesto sockets, 

745-746 
bioradtopgm, 48-49 
bugs, 49 
options, 49 
bit sets, finding first in words, 
921 

Bitmap Distribution Format 
fonts, converting to Portable 
Complied Format, 47 
bitmap widget, 56-57 
bitmaps, 49-57 
CM U, converting to 

portable, 71 
color, 56 
conversion, 49 
cutting and pasti ng, 54 
display, 50 

drawing commands, 51-53 
Edit menu commands, 

53-54 
editing images, 50-51 
File menu commands, 53 
options, 49-50 
Universal ProductCode, 

creating, 368 
widgets, 54-56 
blanks(bash), 12 
block buffered streams, 1016 
block special files, creating, 
325 

BMP files, converting to 

portable pixmaps, 57 
bmptoppm, 57 
bmtoa, 49-57 
/boot directory, 1236 
boot-time parameters 

(kernel), seebootparam 
bootparam, 1216-1224 
Adaptec configurations, 

1219-1220 
argument list, 1216-1217 
BusLogic configuration, 
1220 



busmouse driver parameters, 
1224 

CD-ROM parameters, 

1222-1223 
debug argument, 1217 
Ethernet device parameters, 

1223 

floppy disk driver param- 
eters, 1223-1224 
future domain configura- 
tion, 1220 
hard disk parameters, 

1220-1221 
mem= argument, 1218 
no-hlt argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 

1218 
reserve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI device arguments, 

1218- 1219 

SCSI tape configuration, 
1219 

Seagate ST - Ox confi gu rati on , 
1220 

sound driver parameters, 
1224 

T rantor T 128 configuration, 
1220 

Bourne shell, seesh 
Bourne-again shell, see bash 
brace expansion, 19 
break (shell command), 35 
brk, 746 

browsers, lynx, 306-309 

commands, 308-309 

options, 306-308 
brushtopbm, 57 
bsearchf ) function, 900-901 
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buffchan, 1264-1265 

drop command, 1265 
flush command, 1265 
readmap command, 1265 
buffer-di rty- flush daemon, 

744-745 
buffering streams, 1016-1017 
buffers 

cache, committingto disk, 
869 

filesystem, flushing, 

1401-1402 
flushing from filesto disk, 

756-757 
kernel log, 873 
kernel messagering, reading/ 

clearing, 872-874 
multiple, reading/writing 
data, 1003-1004 
BUG AD D RESS environ- 

ment variable, 529 
buildhash, 274, 279 

files, 281 
builtin (shdl command), 35 
busmouse drivers, boot-tìme 

parameters, 1224 
byefftp command), 148 
byte strings 

comparing, 899-900 
copying, 900 
operations, 901 
writingzerosto, 902 
byte 

counting (in files), 70 
swappingadjacent, 1043 
bzero( ) function, 901-902 

C 



C 

converti ng A N SI to 

Kernighan & Ritchie, 4 
functions, displaying 

headers, 455-456 
preprocessors, 81-84 
imake, 264-267 
options, 82-84 



string tablesource files/ 
headers, 314-315 

seealsogcc 
C++ compila-, seeg++ 
cacheflush, 746-747 

bugs, 747 

errors, 747 

return value, 747 
caches(ARP), manipulating, 
1263 

C Ad ose routine, 964 
cai, 58 

calendar sheets, seegcal 
CAIistopen routine, 964 
calling up systems, 88-90 
calloc( ) function, 976 
canonicalized absolute 

pathnames, 1004-1005 
CAopen routine, 964 
case 

bash command, 13 
ftp command, 148 
cat, 58-59 

catclose( ) function, 903-904 
catgetsf ) function, 902-903 
catopen( ) function, 903-904 
cccp, 81-84 

copying, 84 
options, 82-84 

ed 

ftp command, 148 
shell command, 35-36 
CD-ROMs, boot-tìme 

parameters, 1222-1223 
cdable vars variable (bash), 
18 

CDPATH variable (bash), 16 
cdtin, 516 

seealsotin 
cdup (ftp command), 148 
ceil( ) function, 904 
cfdisk, 1265-1269 

bugs, 1269 

commands, 1267-1268 
options, 1268-1269 
cfgetispeed( ) function, 877, 
1053 



cfgetospeed( ) function, 877, 
1052 

cfingerd, 1106-1109 

bugs, 1108 
error messages, 1108 
features, 1107-1108 
options, 1106-1107 
SYSLOG messages, 1108 
text commands, 1115 
cfingerd .co nf, 1109-1115 
display files section, 

1109-1110 
finger display configure 

section, 1110-1111 
finger fake users files section, 

1114 

finger programs files section, 
1114 

finger strings configure 

section, 1113 
forwarded host section, 

1112 

internai config configure 

section, 1111-1112 
internai strings configure 

section, 1113 
rejected host section, 1112 
services header configure 

section, 1114 
services positions configure 

section, 1114-1115 
signal strings configure 

section, 1113-1114 
system list sites configure 

section, 1112 
trusted host section, 1112 
cfmakeraw( ) function, 1052 
cfsetispeed( ) function, 877, 
1053 

cfsetospeed( ) function, 877, 

1052-1053 
character sets, 1064-1066 

ASCII, 1064, 1214-1216 
ISO 2022, 1066 
ISO 4873, 1066 
ISO 8859, 1064-1065 
ISO 8859-1, 1239-1242 
alphabets» 1240 
characters, 1240-1242 
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KOI8-R, 1065 

Unicode, 1065, 1253-1255 

combining characters, 
1254 

implementation ìe/és, 
1254 

character special files, 

creating, 325 
characters 

classifying, 957-958 
converti ng 

to ASCII, 1055 
wideto multi byte, 
1061-1062 
locating in strings, 953, 
1029 

multibyte, convertingto 
wide characters, 978 

outputting, 997-999 

returning number of bytes 
in, 977 

searching strings for sets, 
1035-1039 

translati ng/deleting, 
536-539 
chat, 727-730, 1269-1273 

abort strings, 1270-1271 

Boolean options, 729 

daemons, 727 

escape menu, 728 

escape sequences, 
1271-1272 

options, 1269-1270 

readdressing, 729 

report strings, 1271 

runtime options, 728-729 

script, 1270 

startupfile, 729 

termination codes, 1272 

time-out value, 1271 

usernamefield, 727 

Xll interface, 730 
chattr, 59-60 
chdir, 747-748 
checkout (cvs command), 
96-97 

checksums, computing on 
files, 501 



chfn, 60 
chgrp, 61 

child processes, creating, 751, 

758 
chkdupexe, 61 
chmod, 61-62, 148, 748-749 

errors, 749 

operators, 62 

options, 62 

return value, 748 

specifying mode, 748 
chooser (xdm), 607 
chown, 62-63, 749-750 

errors, 749-750 

options, 63 
chroot, 750-751, 1273 

errors, 750-751 

return value, 750 
chsh, 63 
ci, 64-69 

controlling file access, 67 

diagnostics, 68 

environment, 68 

filemodes, 67 

options, 65-66 

setuid privi leges, 67-68 

specifying files, 66-67 

temporary files, 67 
cidentd, 69-70 
cksum, 70 
clear, 70-71 

clear-saved-lines( ) action 

(xterm), 715 
clearerr function, 919-920 
clearing terminal screen, 

70-71 
clientlib, 904-905 
clients 

listing running applications, 

669-670 
Remote Start, see rstart 
X, killing, 666-667 
clipboards, X client, 595-597 
buttons, 596 

sending/retrieving contents, 
596-597 



clock, 344, 1273-1274 

colors, 344 

options, 1273 

xclock, 593-595 
clock( ) function, 905 
clocks 

alarm, setting, 744 

CMOS, 1273-1274 

kernel, adjusting, 742-743 
clone, 751 
dose, 752 

ftp command, 148 

telnet command, 508 
closedir( ) function, 905-906 
closelogl ) function, 

1045-1046 
CloseOnExec routine, 965 
CMOS clock, 1273-1274 
C M U bitmaps, converting to 

portatile, 71 
cmuwmtopbm, 71 
co, 71-75 

diagnostics, 75 

environment, 75 

filemodes, 75 

keyword substitution, 74-75 

limitations, 75 

options, 72-74 
col, 76 
coleri, 77 

color, bitmap application, 56 
colrm, 77-78 
column, 78 
columns 

formatting lists into, 78 
removingfrom files, 77-78 

comm, 78-79 
options, 79 

command (shell command), 
36 

command-line options, 

parsing, 937-940 
command oriented history 

variable (basti), 17 
commands 

bitmap application 
drawing, 51-53 
Editmenu, 53-54 
Fi le menu, 53 
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building/ executingfrom 
standard input, 586-587 

cu, 88-89 

cvs, 91-104 

editres, 121-122 

execution, bash, 25 

exit status, 26 

ftp, 148-152 

gpic, 212-213 

history lists, displaying, 39 

info, 269-270 

ispell, 274-275 

locating source/binary and 
manuals files, 575-576 

Ipc, 1317-1318 

lynx, 308-309 

more, 328 

nslookup, 1351-1353 
options, parsing, 207-208 
RCS, 447-449 
readline library, 29-32 
redirection, 21-23 

duplicatingfiledescriptors 
23 

here-documents 22-23 
input, 22 

open ing fi le deaeri ptors 23 
operatore 21 
output, 22 

standard error output, 22 
standard output, 22 

remote execution, 569-571 

sed, 478-479 
grouping, 478 
syntax, 476 

shell (built-in), 35-45 
enabl i ng/disabl i ng, 37 
hdp informati on, 38 

telnet, 508-512 

tftp, 514 

ti mede, 1409 

tin 

articlevi e/ver, 522-524 
editing, 519 

global options menu, 524- 
525 

group index, 521-522 



newsgroup selection, 

519-520 
spool directory selection, 

520 

thread listing, 522 
top, 534-535 
xauth, 588, 591 
zmore, 733-734 
comment-begin variable 

(readline), 28 
comments 
bash, 14 
sed, 477 
commit (cvscommand), 

96-98 
comparing 
files, 78-79 

compressed, 731-732 
strings, 1029-1030 
ignoring case, 1028 
usi ng current locale 1030 
compilers 

g++, 155-160, 174-201 
bugs 160 
copying, 160, 201 
fi lename auffixes, 174-175 
files, 159-160,200 
options 155-159, 

175-178 
pragmas 159, 200 
gec, 174-201 

assembling output, 8-9 
bugs 201 
copying, 201 

fi lename auffixes, 174-175 
files 200 
options 175-178 
pragmas 200 
rpegen, 464-466 
compiling, make utility 
(recompiling programs), 
310-312 
completion-query-items 
variable (readline), 28 
compound commands (bash), 
13 



compressed files 

comparing, 731-732 
compressing/ expanding, 
248-252 
executablefi les, 252-253 
searchingforregular 

expressions, 733 
viewingtext, 733-734 
comsat, 1274-1275 
concatenating 
files, 58-59 

compressed, 251 
portableanymaps, 383 
strings, 1028-1029 
C oncurrent Versions System, 

seecvs 
conditional expressions, 

evaluating, 43 
configurale finger daemon, 
1106-1109 
configuration file, 
1109-1115 
display files section, 

1109-1110 
finger display con figure 

section, 1110-1111 
finger fakeusers files 

section, 1114 
finger programs files 

section, 1114 
finger strings configure 

section, 1113 
forwarded host section, 
1112 

internai confi g configure 

section, 1111-1112 
internai strings configure 

section, 1113 
reiected host section, 1112 
services header configure 

section, 1114 
services positi ons confi gure 

section, 1114-1115 
s'gnal strings con fi gure 

section, 1113-1114 
system list sites confi gure 

section, 1112 
trusted host section, 1112 
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error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 
configuration information, 
getting at runtime, 
1043-1045 
configuring 

network interfaces, 

1304-1305 
rstartd, 469 

keywords, 470 
serial ports, 1394-1395 
SF86_SVGA servers, 

627-628 
SF86_VGA16 servers, 631 
system loggingfile, 

1402-1403 
tinrc, 525-526 
XF86_Accel servers, 

615-616 
XF86_M ono servers, 624 
XFree86, 636 
xfs, 642 

xinetd, 656-660 
confstr( ) function, 906-907 
connect, 752-753 
connections 

dialup IP, handler, 

1285-1288 
displaying active, 1339-1342 
routing information, 1341 
socket information, 
1340-1341 
displaying active routing 

information, 1341 
full-duplex, shutting down, 

855 
socket 

accepting, 740-741 
initiating, 752-753 
listeningfor, 792-793 
console, 1066-1067 
console, codes, 1067-1074 
character sets, 1072 
control characters, 1068 
CSI sequences, 1069-1070, 
1074 



display attributes, 

1070-1071 
ESC sequences, 1068-1069, 

1073-1074 
modeswitches, 1071 
mouse tracking, 1072-1073 
private CSI sequences, 1072 
Set/Reset M ode sequences, 

1071 

status report commands, 
1071 

consolejoctls, 1074-1080 
consoles 

control-character handling, 

1073 
properties, 1067 
sequences, 1067-1074 
character sets, 1072 
control characters 1068 
CSI, 1069-1070, 1074 
display attributes 

1070-1071 
ESC, 1068-1069, 

1073-1074 
modeswitches 1071 
mouse tracking, 

1072-1073 
private CSI, 1072 
Set/Reset M ode, 1071 
status report commands 
1071 

starti ng processes on, 1066 

switching, 1067 

virtual, 1066 

memory, 1101-1102 
continue (shell command), 36 
control messages, 1310 
control operators (bash), 12 
control statements, awk, 167 
control.ctl, 1115-1116 
controlling terminal, getting 

name, 909 
convdate, 79 

conversational exchanges, 
1269-1273 

abort strings, 1270-1271 
chat script, 1270 
escape sequences, 
1271-1272 



report strings, 1271 
termi nation codes, 1272 
time-out value, 1271 
convert-meta variable 

(readline), 28 
converting 

AbekasYUV bytesto 

portablepixmaps, 731 
Andrew Toolkit raster 
objects to portable 
bitmaps, 10 
ANSI C to Kernighan & 

Ritchie C, 4 
ASCII graphics to portable 

graymap, 10 
Atari files 

compresaad Spectrum files 
to portablepixmaps 494 
DegasPll files to portable 

pixmaps 378 
DegasPI3 files to portable 

bitmaps 379 
uncompressed Spectrum 
files to portablepixmaps, 
495-496 
AutoCAD slide files to 

portable pixmaps, 490-491 
Bennet Yee face files to 
portable bitmaps, 726 
Biorad confocal files to 

portable graymaps, 48-49 
bitmap files, 49 
CMU to portable 71 
to portablepixmaps 57 
characters 

to ASCII, 1055 
wideto multibyte 
1061-1062 
dates/times, 79 
to ASCII, 984-986 
to D i scordi an format, 
1210-1211 
documents, troff to LaTeX, 

1252-1253 
doodlebrush files to 

portable bitmaps, 57 
FITS files to portable 
anymaps, 142-143 
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fonts 

Bitmap D i stri buti on 
Format to Portable 
Compi led Format, 47 
packed format to portable 
bitmaps 381 
GEM IMG fi lesto portable 

bitmaps, 201 
GIF fi lesto portable 

anymaps 208-209 
Gould scanner filesto 

portable pixmaps, 211 
groff output toTeX dvi 

format, 227-228 
G roup 3 fax files to portable 

bitmaps, 160-161 
HI PS filesto portable 

graymaps, 256 
H P PaintJet filesto portable 

pixmaps, 381 
ILBM filesto portable 

pixmaps, 263-264 
imagefileto portable 

anymap, 4 
Img-whatnot filesto 

portable pixmaps, 267 
lettere 

tolowercase, 1055-1056 
touppercase, 1055-1056 
Lisp machine bitmap filesto 

portable graymaps, 292 
M acintosh PICT filesto 

portable pixmaps, 379-380 
M acPaint filesto portable 

bitmaps, 309-310 
M GR bitmaps to portable 

bitmaps, 322-323 
multibyte characters to wide 

characters, 978 
multibyte stringsto wide 

character, 977-978 
object codeinto N LM 

outfiles, 338-339 
PCX filesto portable 

pixmaps, 368-369 
Photo-C D filesto portable 

pixmaps, 260-261 



portable anymaps 
toDDIF format, 396 
toFITS format, 396-397 
to PostScript, 397 
toSGI imagefile 

398-399 
to Solitaire format, 399 
toSun raster files, 398 
to TIFF files, 399-400 
intoXll window dumps, 

400 

portable bitmaps 

to Andrew Tool kit raster 

objects 358 
toASCII graphics 357 
to Atari DegasPI3 files, 

364 

to Bennet Yee"face" files 
367 

to BitGraph graphics 358 
to CM U window manager 

bitmaps 358-359 
to compressed G raphO n 

graphics 360-361 
toDEC LN 03+ Sixei 

output, 362 
to encapsulated PostScript- 

style bitmaps 359 
to Epson printer graphics 

359 

toGEM IMG files 360 
to Gemini lOx graphics 
356 

to Group 3 fax files 360 
toHP LaserJet format, 

361-362 
toM acP ai nt files 363 
to M GR bitmap, 363 
to packed format fonts 

364- 365 

to portable graymaps 364 
to PostScript, 362 
to Printronix printer 

graphics 366 
to Sun icons 361 
toUNIX plot files 

365- 366 



toXIO bitmaps 366 
toXll bitmaps 367 
toZinc bitmaps 367-368 
portable graymaps 
to Lisp machine format, 

376-377 
to portable bitmaps 377 
to portable pixmaps 378 
toUsenix FaceSaver 

format, 376 
portable pixmaps 

toAbekasYUV files, 428 
to Atari D egas PI 1 files, 

422 

to AutoCAD, 414-416 
to BMP files, 416 
to D EC sixel format, 

425-426 
to GIF files 416-417 
toHP PaintJet files 423 
toHP PaintJet XL PCL 

files, 424 
to ILBM files 418-419 
to Macintosh PICT files, 

422-423 
toM itsubishi S340-10 

files, 420-421 
toMotifUIL icon files, 

427 

toNCSA ICR format, 

417-418 
to PCX files 421 
to portable graymaps 

421-422 
to red/blue3D glasses 

400-401 
to three portable graymaps 

425 

to three raw YU V files 

428-429 
to TrueVision Targa files 

426 

toXll pixmaps 427-428 
toXll puzzlefiles, 
424-425 
PostScript filesto portable 
anymaps, 434-435 
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PostScript imagedata to 
portablegraymap, 
433-434 
QRT raytracer output to 

portable pixmaps, 436-437 
raw grayscale bytes to 

portable graymaps, 439 
raw RG B bytes to portable 

pixmaps, 439-440 
ray tracer output to portable 

pixmaps, 333 
SGI image files to portable 

anymaps 483-484 
Solitai re files to portable 

anymaps 488-489 
spaces to tabs, 559 
SPOT satellite imagesto 
portable graymaps, 495 
strings 

ASCII to doublé 

1039-1040 
to long integers 1041 
to unsigned long integers 

1041-1042 
wide character to 
multi byte character, 
1061 

Sun iconsto portable 

bitmaps, 262 
Sun raster files to portable 

anymaps 438 
tabs to spaces, 137 
TIFF files to portable 

anymaps, 515-516 
times 

initializing information, 

1058-1060 
to ASCII, 984-986 
totm structure, 1036- 

1037 

TrueVision Targa fi lesto 
portable pixmaps, 515 

Usenet batch fi lesto IN N 
format, 1281-1282 

Usenix FaceSaver files to 
portable graymaps, 147 



Xll orXIO bitmaps to 

portable, 592 
Xll pixmaps to portable, 

677 

X11/X10 window dump 
fi lesto portable anymaps, 
722 

Xconfigfileformatto 

XF86Config, 454 
XI M files to portable 

pixmaps, 654 
XV thumbnail picturesto 

portable pixmaps, 720 
YUV files to portable 
pixmaps, 730-731 
convolution kernel s, generat- 
iti^ 372-373 
cookies, generating, 317 
copying 
ar utility, 7 
as, 9 

byte strings, 900 
files, 80-81 

converti ngwhi le, 108-109 
instali, 272-273 
MS-DOSto/fromUNIX, 

317-318 
U N IX-to-U N IX, 
563-565 
M S-DOSfilesto UNIX, 
329 

number signs, 907 

strings, 1030-1031 
stpcpy( ) function, 
1027-1028 
copysign( ) function, 907 
cos( ) function, 907 
cosh( ) function, 908 
cosines, 907 
cp, 80-81 
cpp, 81-84 

copying, 84 

options, 82-84 
CPU, listing most intensive 

processes, 533-535 
cr (ftp command), 148 
creat, 815-816 



create, module, 800-802 
crond, 1275 
crontab, 84-85 
crypt function, 908-909 
esplit, 85-86 
ctags, 87-88, 135-137 
bugs, 88 

copying, 136-137 
files, 87 

options, 87, 136 
ctermid( ) function, 909 
ctime, 909-910, 984-986 
ctlinnd, 1276-1279 

bugs, 1279 

commands, 1276-1278 
Ctrl+Alt+Del combination, 

setting function, 1279 
etri alt del, 1425 
ctrlaltdel, 1279 
cu, 88-90 

bugs, 90 

commands, 88-89 

options, 89-90 
cuserid( ) function, 934-935 

bugs, 935 

errors, 934 

files, 935 
cut, 90-91 

cut buffers, copying selections 

into, 598-599 
cvs, 91-106, 1116-1120 

commands, 91-104 
add, 96 
admin, 96 
checkout, 96-97 
commit, 96-98 
diff, 98 
export, 98 
hi story, 99 
import, 100 
log, 100 
rdiff, 101 
release. 101 
remove, 101-102 
rtag, 102 
status, 102 
tag, 102-103 
update 103-104 



1444 



CVS 



environment variables, 
105-106 
CVSJGN ORE_REM OTE 

_ROOT, 105 
CVS_RSH, 106 
CVS_SERVER, 106 
CVSEDITOR, 105 
CVSREAD, 105 
CVSROOT, 105 
CVSWRAPPERS, 106 
RCSBIN, 105 

files, 104-105, 1117-1119 

options, 92-104 

checkout command, 97 
commi t command, 97 
h i story command, 99 
import command, 100 
rdiff command, 101 

sending problem reports, 

1279- 1281 
filling out reports 

1280-1281 
startup file, 93 
support files, 1116-1120 
CVSJGNOREREMOTE 
ROOT environment 
variable, 105 
CVS RSH environment 

variable, 106 
CVS_ SERVER environment 

variable, 106 
cvsbug, 1279-1281 
EM AC S interface, 1281 
environment, 1280 
files, 1281 
filling out reports, 

1280- 1281 
options, 1280 

CVSEDITOR environment 

variable, 105 
CVSREAD environment 

variable, 105 
CVSROOT environment 

variable, 105 
CVSWRAPPERS environment 

variable, 106 



cvtbatch, 1281-1282 
Cycladesdrivers, tuning, 

1282-1284 
cytune, 1282-1284 

bugs, 1283 
options, 1283 

D 



daemons 

buffer-dirty-flush, 744-745 
configurable finger daemon, 
1106-1109 
confi gu rati on file, 

1109-1115 
error messages, 1108 
features, 1107-1108 
SYSLOG messages» 1108 
cron, 1275 

InterNetNews, 1309-1312 
control messages, 1310 
controling, 1276-1279 
kernel log, 1315-1317 
line printer spool er, 

1318-1320 
network routing, 1380-1382 
NFSmount, 1332-1333 
NFS servi ce, 1347 
powerd, 1359-1360 
pppd, 1360-1369 
ti me server, 1407-1408 
UUCP file transfer, 
1415-1417 
DARPA 

FTP server, 1301-1304 
requestssupported, 
1302-1303 
port numbers, converting 
PRC program numbers to, 
1358-1359 
Telnet server, 1406-1407 
T FT P server, 1407 
data buffers, flushing from 

files to disk, 756-757 
data cache, flushing contents, 

746-747 
data segments, changing, 746 



databases 

bibliographic, 219 
fields, 219 

inverted indexes, 209-210 
seardiing, 210, 292-293 
filename, updating, 561-562 
files, searching for patterns, 

295 
news overview 
expiring entries, 

1293-1294 
format, 1168-1169 
updating, 1353-1354 
ps, updating, 436 
rebuilding for mail aliases 

file, 336 
RGB colorname, 

uncompiling, 488 
terminal capability, 
1188-1197 
boolean capabilities, 1189 
numeric capabi I iti es, 

1189- 1190 

stri n g capabilities 

1190- 1197 
Usenet, recovering, 1342- 

1344 
date, 106-108 

arguments, 106-107 
files, 108 
options, 108 
dates/times 
converting, 79 
to ASCII, 909-911, 

984-986 
to D i scordi an format, 

1210-1211 
stri ngs to numbers 
989-990 
formatting, strftime( ) 
function, 1032-1034 
returning current, 928-929 
setting, 107-108 
showing, 106-107 
dd, 108-109 
ddate, 1210-1211 
D D check routine, 965 



di rectory trees 
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D D end routine, 965 
D D start routine, 965 
debug (ftp command), 149 
debugfs, 1284-1285 

commands, 1284-1285 

options, 1284 
declare (shell command), 36 
del timer, 1424 
delete module, 800-802 
delete (ftp command), 148 
deleting 

binary treeitems, 1056 

directories, 829-830 

M S-D OS directory trees, 
319 

M S-D OSfiles, 318-319 
depmod, 109-112 

configuration, 110-111 

files, 111 

strategy, 111 
descriptor tables, size 

(getting), 760-761 
descriptors, testing, 958-959 
/dev directory, 1236 
devices 

bad blocks (searching for), 
1264 

controlling, 774-788 
ioctl calls(listof), 
775-786 
creating, 815-816, 

1321-1324 
describing ali, 1120-1121 
disk, ram, 1094-1095 
DOS (tableof), 1152-1158 
Ethernet, boot-time 

parameters, 1223 
floppy disk, 1080-1083 

configuration, 1080-1082 
hard disk, 1083 
line printer (ioctlf ) cai I s) , 

1090-1091 
Ip, parameters ( setti ng), 

1413-1414 
opening, 815-816 
PLIP, timing parameters, 

1357 



SCSI tape, drivers, 

1096-1100 
setup, 849 
swapping 

enabling/disabling, 1401 
starti ng/stoppi ng, 866-867 
terminal (list of), 1197 
DEVINFO, 1120-1121 
df, 112-113 

dialup IP connection handler, 
1285-1288 

dialin mode, 1286-1287 

dialout mode, 1287-1288 
dictionaries, compressing/ 

uncompressing, 496 
diff (cvs command), 98 
difftime, 911, 984-986 
dig, 113-117 

bugs, 117 

environment, 117 

files, 117 

options, 114-115 
dip, 1285-1288 

command mode, 1285-1286 

dialin mode, 1286-1287 

dialout mode, 1287-1288 

files, 1288 
dir, 303-304 

bugs, 304 

ftp command, 149 

options, 303-304 
directories 

/, 1236 

addingto stack, 40 
alphabetizing entri es, 

1012-1013 
/bin, 1236 
/boot, 1236 

changing, 35-36, 747-748 
closing, 905-906 
creating, 323 

mkdir, 794-795 

mknod, 795-796 
deleting, 829-830 
/dev, 1236 
displaying list of, 36 
/dos, 1236 



/etc, 1236 
/etc/skel, 1236 
/etc/Xll, 1236 
files (searching for), 137-142 
getting current, 931 
getting entries, 759 
filesystem-independent 
format, 931-932 
hierarchies, creating, 323 
/home, 1236 
/lib, 1236 

listingcontents, 303-304 
/mnt, 1236 
MS-DOS 

changing, 316-317 

displaying, 319 
opening, opendir, 989 
printing pathnames, 40 
/proc, 1236 
promoting, 39-40 
RCS, creating, 447-449 
reading 

entries 823 

readdi r( ) function, 
1002-1003 
removi ng, 462 
root, changing, 750-751, 

1273 
/sbin, 1237 
scanning for matching 

entries, 1012-1013 
stream, resetting, 1011 
/tmp, 1237 

trees, walking through, 930 
/usr, 1237 
/usr/XHR6, 1237 
/usr/XHR6/bin, 1237 
/usr/XHR6/lib, 1237 
/usr/XHR6/lib/Xll, 1237 
/usrXHR6/include/Xll, 
1237 

directory stream, current 

location (returning), 1048 
directory trees 

MS-DOS, deleting, 319 
shadow directories 
(creating), 294 



1446 



dirsfsheìl command) 



dirs (shell command), 36 
disconnect (ftp command), 
149 

D iscordian dates (converting 

to), 1210-1211 
disks 

adding M S-DOS filesystems 

to, 321-322 
devices, ram, 1094-1095 
displaying usage/limits, 437 
floppy 

formatti ng, 1295-1296 
marking bad blocks, 316 
setti ng parameters 1391 
M S-DOS, mounting, 

326-327 
quotas, manipulating, 

821-822 
SCSI, drivers, 1095-1096 
summarizingfree space, 

112-113 
summarizing usage, 120-121 
Xdf, 332 
display argument command 

(telnet), 508 
DISTRIBUTION environ- 

ment variable, 529 
div( ) function, 911 
dividing integers, 911 
floating-point remainders, 

913, 923 
returning quotient and 
remainder, 961 
dmesg, 1288-1289 
dncomp, 1008-1011 
dnexpand, 1008-1011 
dnsdomainname, 259-260 
dnsquery, 117-119 
bugs, 119 
diagnosta, 118 
files, 118 
options, 117-118 
docilmente 

converting, troff to LaTeX, 

1252-1253 
formatting, gtroff, 237-248 



dollar signs ($) 

bash special parameters, 15 
expansion, 19 
ftp command, 148 
domain names 
current host, 119 
displaying, 259-260 
getting/setting, 760 
querying servers, 117-119 
sending query packets to 

servers, 113-117 
servers, resolver routines, 
1008-1011 
domain servers, looking up 
hostnameswith, 257-258 
domainname, 119 
domains, nameserver, 
1334-1338 
querying, 1350-1353 
doodle brush files, converting 

to portable bitmaps, 57 
DOS devices, table of, 

1152-1158 
/dos directory, 1236 
drand48( ) functions, 912 
drawing bitmaps (commands), 

51-53 
drem( ) function, 913 
drivers 

busmouse, boot-time 

parameters, 1224 
Cyclades, tuning, 

1282-1284 
floppy disk, boot-time 

parameters, 1223-1224 
SCSI disks, 1095-1096 
SCSI tape devices, 
1096-1100 
ioctl( )calls 1097-1100 
sound, boot-time param- 
eters, 1224 
dsplit, 119-120 
du, 120-121 
dumpe2fs, 1289 
dumping files, 345-346 
dup, 753-754 



dup2, 753-754 

duplicate executables, finding, 
61 

duplicating strings, 1031 

E 



e-mail 

notification, 48 
sending, 1387-1390 
aliases, 1390 
e2fsck, 1289-1291 
bugs, 1291 
exit code, 1290 
options, 1290 
echo (shed command), 36-37 
ECHO REQUEST packets, 

sending, 1358 
ecvt( ) function, 913-914 
Edit menu commands, bitmap 

application, 53-54 
editing bitmaps, 49-51 
editing-mode variable 

(readline), 28 
edito rs 

emacs, 130-133 
bugs 133 
di stri buti ng, 133 
files, 132-133 
manuals 132 
mouse button bindings 

132 
options 130 
X Window System, 
131-132 
stream-oriented, seesed 
editres, 121-126 

beginning sessions, 121 
blocking requests, 124 
commands, 121-122 
environment, 126 
files, 126 
options, 121 
resource box, 123-124 
resources, 124-125 
widgets, 125-126 
window, 121 



environment vari ables 



edquota, 1291-1292 
egrep, 224-226 

bugs, 226 

diagnostics, 226 

options, 224-225 

regular expressions, 225-226 
$é se parser di recti ve 

(readiine), 29 
elvis, 126-128 

bugs, 128 

environment, 127-128 

files, 127 

options, 127 

ref interaction, 455 

tag files, 135-137 
elvprsv, 128-129 
elvrec, 129-130 
emacs, 130-133 

bugs, 133 

distributing, 133 

files, 132-133 

function key/mousesupport, 

134-135 
manuals, 132 

mouse button bindings, 132 

options, 130 

tag files, 135-137 

using emacstool with, 135 

X Window System, 131-132 
E M AC S user interface, 

cvsbug, 1281 
emacstool, 134-135 

bugs, 135 

environment variables, 135 

files, 135 

options, 134 

using with emacs, 135 
enable (sheJI command), 37 
encoded files, uuencode 

format, 1200 
encryption 

crypt function, 908-909 

memory areas, 980-981 
endgrent( ) function, 932-933 
$endif parser direttive 
(readiine), 29 



endmntent( ) function, 

935- 936 
endnetent subroutine, 

936- 937 
endprotoent( ) function, 

941-942 
endpwentf ) function, 943 
endserventf ) function, 946 
endusershell( ) function, 

946-947 
endutent( ) function, 947 
ENV variatale (bash), 16 
environ, 1121 
environ command (telnet), 

511 

environment variables 

adding/changing, 996-997, 

1017 
bash, 25-26 
ci, 68 
co, 75 

cvs, 105-106 
CVSJGNORE 
_REMOTE_ROOT, 
105 

CVS_RSH, 106 
CVS_SERVER, 106 
CVSEDITOR, 105 
CVSREAD, 105 
CVSROOT, 105 
CVSWRAPPERS, 106 
RCSBIN, 105 

cvsbug, 1280 

dig, 117 

editres, 126 

elvis, 127-128 

emacstool, 135 

fsinfo, 145 

fslsfonts, 146 

fstobdf, 146 

ftp, 154 

gawk, 172 

getoptf ) function, 939 
getting, 932 
groff, 229 
gtroff, 248 
gzip, 251 



imake, 267 

info, 270 

Id, 291 

Ikbib, 293 

locate, 295 

Ipq, 299 

Ipr, 300 

Iprm, 302 

more, 328 

nslookup, 1353 

rcs, 443 

rcsclean, 444 

rcsdiff, 445 

rcsmerge, 450 

ref, 455 

rlog, 459 

rlogin, 461 

script, 475 

startx, 497 

tcal, 506 

telnet, 512 

tin, 528-530 

AD D_AD D RESS, 529 
AUTOSUBSCRIBE, 529 
AUTOUNSUBSCRIBE, 
530 

BU G_AD D RESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
N NTPSERVER, 529 
ORGAN IZATION , 529 
REPLYTO, 529 
T I ACT I V E F I L E, 529 
TI N OVROOTDIR, 529 
TIN HOM EDIR, 528 
T I N _ I N DEXDIR, 529 
T IN LIBD I R, 529 
TIN SPOOLD IR, 529 
TIN RC, 528 
VISUAL, 529 

tset, 541 

twm, 557 

TZ,987 

ul, 559 

xauth, 589, 592 
xclipboard, 597 
xclock, 595 
xcmsdb, 593 
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xconsole, 598 
xdm, 608 
XFree86, 637 
xhost, 644 
xinit, 666 
xlogo, 668 
xlsatoms, 669 
xlsclients, 669 
xlsfonts, 671 
xmodmap, 675 
xprop, 680 
xrdb, 684 
xrefresh, 685 
xstdcmap, 700 
xterm, 717 
xwd, 722 
xwininfo, 724 
xwud, 726 
eqn, seegeqn 

equation formatting, 202-206 
erand48( ) functions, 912 
erf( ) function, 914 
erfc( ) function, 914 
ermo, 916-917 
error functions, 914 
errore 

access, 741 

adjtimex, 743 

bdflush, 745 

bind, 745-746 

cacheflush, 747 

chdir/fchdir, 747-748 

ehm od, 749 

chown, 749-750 

chroot, 750-751 

clone, 751 

dose, 752 

codes, describing (returning 

strings), 1032 
creat, 816 
dup/dup2, 753 
execve, 754 
fchmod, 749 
fchown, 749-750 
fcntl, 756 
fdatasync, 757 
fork/vfork, 758 



fsync, 759 

getdents, 759 

getdomainname, 760 

getgroups, 762 

gethostname, 763 

getitimer, 764 

getpeername, 765 

getpriority, 766-767 

getrlimit, 768 

getsid, 768 

getsockname, 769 

getsockopt, 771 

gettimeofday, 773 

idle, 774 

ioctl, 774 

iopl, 789 

kill, 790 

killpg, 791 

link, 791-792 

li sten, 792 

llseek, 793 

Iseek, 794 

mkdir, 795 

mknod, 796 

mlockall, 798 

mmap, 799 

modifyjdt, 800 

mount, 803 

mprotect, 804 

mremap, 806 

msgctl, 807 

msgget, 808 

msgop, 810 

munlock, 812 

munmap, 799 

mysne, 811 

nanosleep, 813 

nice, 814 

open, 816 

pause, 817 

personal ity, 818 

return value, 797 

returning number, 916-917 

setdomainname, 760 

setgroups, 762 

sethostname, 763 

setiti mer, 764 



setpriority, 766-767 

setrlimit, 768 

setsockopt, 771 

settimeofday, 773 

symbol ic error names, 
916-917 

unmount, 803 
escape character, bash, 14 
etags, 135-137 

copying, 136-137 

options, 136 
/etc directory, 1236 
/etc/modulesfile, 1152 
/etc/skel directory, 1236 
/etc/X 11 directory, 1236 
Ethernet devices, boot-time 

parameters, 1223 
Euclidean distance(finding), 
953 

EUID variatale (bash), 15 
eval (shell command), 37 
event timers, managing, 1424 
ex, see dvis 
exclamation points (!) 

bash special parameters, 15 

ftp command, 148 
exec (shell command), 37 
execl function, 914-916 
execle function, 914-916 
execlp function, 914-916 
exect function, 914-916 
executable files, compressing/ 

expanding, 252-253 
executables, duplicate 

(finding), 61 
executing programs, 754-755 

pausing, 813-814 

suspending, 1061 
execv function, 914-916 
execve, 754-755 
execvp function, 914-916 
exit, 739-740, 917 

shell command, 37 

xauth, 591 
exit status (commands), 26 
exp( ) function, 918 
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expand, 137 
expand-tildevariable 

(readline), 28 
expanding files, see compress- 

ing/expanding files 
expansion, 18-21 
arithmetic, 20 
brace, 19 

command substitution, 20 

history, 33-34 

event designators 33 
modifiers 34 
word designators 33 

parameter, 19-20 

pathname, 21 

process substitution, 20 

quote removal, 21 

tilde, 19 

word splitting, 21 
expire, 1292-1293 
expire.ctl, 1121-1123 
expireover, 1293-1294 
expml( ) function, 918 
exponents, 918 
export 

cvs command, 98 

shell command, 37 
exported kernel symbols, 

displaying, 284-285 
exports, 1123-1125 

files, 1124 

options, 1123 

user ID mapping, 
1123-1124 
expressions 

conditional, evaluating, 43 

find, 138 

gawk, 166 

gpic, 213-214 

grep, 225-226 

label, grefer, 223-224 

numeric, gtroff, 239 

regular, sed, 476-477 
ext fi lesy sterri, 1125 
ext2 filesystem, 1125 
extracting from archi ves, 5-7 



F 



fabs( ) function, 919 
face files, converting to 
portable bitmaps, 726 
fastrm, 1294-1295 
fc (shell command), 37-38 
FCEDIT variable (basti), 17 
fchdir, 747-748 
fchmod, 748-749 
fchown, 749-750 
fclose function, 919 
fcntl, 755-756 
fcvt( ) function, 913-914 
fd, 1080-1083 

configuration, 1080-1082 

ioctlf ) calls supported, 1082 
FDCLR macro, 836 
FD ISSET macro, 836 
FD SET macro, 836 
FD ZERO macro, 836 
fdatasync, 756-757 
fdformat, 1295-1296 
fdisk, 1296-1297 
fdopen function, 924-925 
feof function, 919-920 
ferror function, 919-920 
fflush function, 920-921 
ffs( ) function, 921 
fg (shell command), 38 
fgetc( ) function, 945 
fgetgrent( ) function, 921-922 
fgetpos function, 927-928 
fgetpwent( ) function, 

922-923 
fgets( ) function, 945 
fgrep, 224-226 

bugs, 226 

diagnosta, 226 

options, 224-225 

regular expressions, 225-226 
fields, awk, 163 
FIFOs(named pipes), 1403 

creating, 323-325, 982-983 

system logging, 1403 
FIGNORE variable (bash), 17 



filedescriptors 

duplicating, 23 

manipulating sets, 836 

opening, 23 

readingfrom, 822 

writingto, 889-890 
File menu commands, bitmap 

application, 53 
filetable 

addingentries, 1428-1429 

description, 1425-1426 

initializing, 1427 

moving files to end, 1431 

removing files, 1431-1432 

structure, 1426 

table entries, 1426 

unreferenced entries, 
fetching, 1428 
file-creation mask, setting, 45 
file_table, 1425-1426 

table entries, 1426 

table structure, 1426 
file table init, 1427 
filechan, 1297-1298 
Alenarne databases, updating, 

561-562 
filenames 

matching, 924 

temporary, creati ng, 
983-984 
fileno function, 919-920 
files 

aborting transfer, 152 
access permissions, 
changing, 61-62 
agetty, 1261 
Atari 

compressed Spectrum, 
converting to portable 
pixmaps, 494 

DegasPll, converting to 
portable pixmaps 378 

D egas P 1 3, converting to 
portable bitmaps, 379 

uncompressed Spectrum, 
converting to portable 
pixmaps 495-496 
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attributes, 59 

changing (second extended 
fi le system), 59-60 
authority (X), xauth file 

utility, 587-592 
AutoCAD slide, converting 
to portablepixmaps, 
490-491 
bash, 46 
binary 

encodi ng/decodi ng, 

565-566 
locatingfor commands, 
575-576 
Biorad confocal, converting 
to portablegraymaps, 
48-49 
bitmap, converting, 49 

to portablepixmaps, 57 
block special, creating, 325 
character special, creating, 
325 

comparing, 78-79 
compresseci 

comparing, 731-732 

searchingfor regular 
expressìons, 733 

viewing text, 733-734 
compressing/ expanding, 
248-252 

concatenation, 251 

executablefiles, 252-253 
computing checksums, 501 
concatenati ng, 58-59 
configuration values, getting, 

925-926 
copying, 80-81 

betwean machines, 
440-441 

converting while 108-109 

instali, 272-273 
counting bytes/words/lines, 

70, 574 
creating, 815-816 

masks, 880 
cuseridf ) function, 935 
cutting sectionsfrom, 90-91 



cvs, 104-105, 1117-1119 

startup, 93 
cvsbug, 1281 
database, searchingfor 

patterns, 295 
date, 108 
descriptors 

ci osi n g, 752 

duplicating, 753-754 

manipulating, 755-756 
domainname, 119 
doodle brush, converting to 

portable bitmaps, 57 
dumping, 345-346 
/etc/modules, 1152 
executing, 914-916 
exports, 1124 

face, converting to portable 

bitmaps, 726 
filesystem description, 
accessi ng, 935-936 
filters, hexdump, 254-256 
FITS, converting to portable 

anymaps, 142-143 
font, 1128 

adding font-metric 

informati on, 2 
creating, 3 

groff (creating for), 513 
formats, converting Xconfig 

toXF86Config, 454 
free, 144 

gcc/g++, 159-160, 200 
GEM IMG, converting to 

portable bitmaps, 201 
GIF, converting to portable 

anymaps, 208-209 
Gould scanner, converting 

to portablepixmaps, 211 
group, getting entri es, 

921-922, 932-934 
group ownership, changing, 

61 

gtroff, 248 

gzip, forcing .gz extension, 
732-733 



H IPS, converting to 
portablegraymaps, 256 

H P PaintJet, converting to 
portablepixmaps, 381 

httpd, 261 

identifying processes, 154- 
155 

identifying RCS keyword 

strings in, 262-263 
ifconfig, 1305 
ILBM , converting to 

portable pixmaps, 263-264 
image, converting to 

portable anymap, 4 
imake, 266 

Img-whatnot, converting to 

portablepixmaps, 267 
joiningfields, 282-283 
linking, 293-294, 791-792 
Lisp machine bitmap, 

converting to portable 

graymaps, 292 
listi ng attributes, 304-305 
location, changing, 828-829 
lock, creating for shell 

scripts, 487 
login, 297 

login record, 1198-1200 

M acintosh PICT, convert- 
ing to portablepixmaps, 
379-380 

M acPaint, converting to 
portable bitmaps, 309-310 

MAKEDEV, 1321 

makefiles, creating 
dependencies in, 312-314 

man, 1248 

manual page, locatingfor 
commands, 575-576 

mapping/unmapping, 
799-800 

merging 
lines 347 
three-way, 320 

mesg, 321 

modprobe, 111 

mount, 1332 
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\m ri t-i nn 07 1 07 3 

wn ti ng, y / i-y / z 


fArvì r\ \ ji ^C1 ^C3 

removi ng, 4oi-4oz 


names 


r\r\ri"^irì 1 & r\ii"rvi ^ìri 

puriaDic uitmdp 


r*n 1 1 m n r 77 7 Q 

LOiumnsa, //-io 


rhanninn P3P P3Q 

Liidnyiny, ozo ozy 


fnrmat 1 1 70 1171 
lui nidi, 1 1 / u il / 1 


a±c n f 1 3Q/I 1 3QC; 

icibui, izy^-izyj 


a i spi ayi n g rrom u ssn se 


reaui ng, yoo 


r*^r\ ^rrt i 33/1 33R 

renami ng, 334-333 


hid-nrv fi lo 33fi 337 
111 blUI y 1 1 le, ZZO ZZ 1 


lA/rifinn Qfifi QfiQ 

w 1 1 li ny, yoo yoy 


rocril\/o.r rTinfini irarinn 
IcbUIVcl LUMI lyUI dLIUIl, 


nammn rnnwonrinnc 1 R3 
1 Idll II 1 iy LUI 1 Va ILI Ul Ib, 1JJ 


pui LdUlc yidyllldp 


11 P3 n pA 
110 3 llOf 


narrr 1 R3 1 RA 


fnrmal- 1171 1173 
lUl llldl, 11 1 1- 11 1 L 


ro\/Qrcir\n linoc A^~I 
ICVeibllig llllcb, 4D / 


M 1 M mirfilaz rn nworri n ri 
IM L l v l UULI Ileo, LUI Iva Lilly 


rc^H inn 070 

i edui ny, y / u 


CQarr"hì i nn f nr l i n rli ro/~rnri qc^ 
bcdlLlllliy IUI [ili Ul 1 CL.LUI lebj 


nnioct 1 rnria infn 33D 330. 

ouject coue mio, 330-33? 


iai r i i"i n n 07 0 

w 1 1 u ny, y / u 


1 37 1 A3 
13 f- 14Z 


nnnrovr nnnrinn crrmnc 
MUllLcAL, pi 1 11 LI lly bLI lllyb 


pUl LdUlc piXINdp 


QPPf^r* nnfim non orari n m 

jr 00L- uni iy, yciitì dLiny, 


frnm AQP 
1 1 uni, t-jO 


fnrm^t 1173 11 IL 
IUI llldl, 11 / 3 11 i 4 


fi33 


r\ i 1 m K or i r\ ri li noe 3 37 3 3D 

numuenng nnes, 33/-330 


rn^rJ i nn 07/1 

icdui ny, y /4 


1 iiiidye, LUiiveiLiiiy lu 


object 


wn ti ng, y /4 


portauie anymaps, 


copyi ng/transati ng, 


D r\r4"C r* ri r\ f rr\ r\ \ /r\rf i r\ r^ 4~r\ 

rostbcript, convertingto 


A P3 A QA 
40J-404 


3A1 3A3 

j4 1 - J4Z 


pUl LdUlc dllyllldpb, fjf- 


eh ar 1 1 n nari/ i n ri RfiO Rfil 
blldl, UlipdLìs.lliy, JOU JUl 


discarding symbolsfrom, 


/I 3c: 
4oD 


shrinking, 488 


AQQ 


plebei Vlliy dlLa Lldbllcb, 


Qnlirairo rnnworrinri rn 
jUIILdllc, LUIlvcl Llliy LU 


ri i mi awi n n in fnr m ^t - 1 nn 

UlbfJlaylliy 1 11 IUI llldll Ull 


1 3p i 3Q 

izo- izy 


r\r\ r f^K q nr\ \ /rv> une 

portauie anymapb, 


frnm 3/1") 3/13 


printer/plotter accounting, 


A PP A PO 

4oo-4oy 


li d"i n n mrti nn an H tntal 
11 ìli ny jclli un anu luidi 


rpaHinn I^RA-I^RR 
icduuiy, ijj t t _ ijjj 


CTìr+oH romrìuìnri rli i ni i rato 
bui LCU, 1 CI 1 IUVM iy uu pn LdLC 


d 7oz APG AGO 

yzsa. 4oy-4yu 


pilllLlliy, IN Icvcibc, DUj-DU4 


nnes, dou 


i c+i n n n/iYi Knl c frnm 

1 1 !ii ny bymuui b 1 1 uni, 


r\ rr\ fr\ cc\ ri ori r\ if mr\ 1 1 DO 

piULULUI UcTirilLIUll, 110U - 


ct~\ 1 irro Inr^finn f r\r 

buuiLe, lULdLing iui 


330 3/10 
3 3y- J4U 


1 1 0.1 
llol 


commanos, d/d-d/o 


offsets, repositi oning, 




spell-checking Utilities, 281 


703 70/1 

/yj- /y4 


cnangi ng attri Dutes, 


cnliffinn PR Pfi 110 130 

spntting, oD-oo, iiy-izu, 


r\ non inrt P 1 ^ P 1 £ 
Upallliy, 01j - 010 


AA1 AA3 
441-44 3 


AQA AQR 

4y4-4yj 


arivi enrv 1 nrVc / anni \/i nn/ 
au vi jui y i uuso \ appi yi i iy/ 


Licaiiiiiy, ttj ttj 


DiaiUD, ycLLiiiy, ouj out 


removi ng), 757 


comparìng revisions» 


string table C sourcefiles/ 


outputting 


445-446 


headers, 314-315 


endsof, 504 


control 1 i ng access, 67 


substituting definitions into, 


headers 253-254 


format, 1181-1183 


500-501 


ownership, changing, 62-63, 


freezing confi gu rati on, 


suffixes, list of, 1249-1252 


749-750 


446-447 


Sun raster, convertingto 




modes 67 


portabl e anymaps, 438 
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file 



swapping 

enabl i ng/disabl i ng, 1401 
starti ng/stopping, 866-867 

symbolic links, 867-869 

synchronizing 

in-coredata, 756-757 
in-corestate, 758-759 
with memorymaps 811 

tag 

emacs, 135-137 

vi, 135-137 
tags, generati ng, 87-88 
tempo rary 

creating, 983, 1053-1054 

naming, 1049, 1054 
text 

converti ngfor printing, 

429-430 
creating gcal resourcefiles 

from, 558 
sorting, 492-493 
TIFF, converti ngto portable 

anymaps, 515-516 
timezone informati on, 

1197-1198 
timestamps (changing), 536 
transfer parameters, 153 
TrueVision Targa, convert- 
ingto portable pixmaps, 
515 

truncating, 879-880 
UNIX 

copyi ng between systems, 

563-565 
copyi ngto MS-DOS, 335 
restori ng fi lenames. 324- 
325 

U senix FaceSaver, convert- 
ing to portable graymaps, 
147 

user group, 1131 
UUCP transfer requests, 
processing, 1415-1417 
uuencode, format, 1200 
XFree86, 638-639, 
1201-1208 
Devi ce sections 
1204-1206 



Filessection, 1201 
Keyboard secti on, 1202 
M onitor sections 

1203-1204 
Pointer secti on, 

1202-1203 
Screen sections, 
1206-1208 
ServerF lagssecti on, 1201 
XI M , convertingto portable 

pixmaps, 654 
YUV, convertingto portable 

pixmaps, 730-731 
Z, recompressingto GZ, 

734-735 
Zeiss confocal, converting to 
portable anymaps, 732 
filesystem checks 

group identity ( setti ng), 

843-844 
user identity (setting), 844 
filesystem description file, 

accessing, 935-936 
filesystems, 1125-1126 
buffers, flushing, 1401-1402 
building, 1325-1326 
checking, 1298-1300 
debugger, 1284-1285 
commands, 1284-1285 
options, 1284 
deleting namesfrom, 1008 
device entries, maintaining, 

1320-1321 
dumping information, 1289 
ext, 1125 
ext2, 1125 

hierarchy, description of, 

1236-1238 
H igh Sierra, 1125 
hpfs, 1125 
iso9660, 1125 
M IN IX, 1125 
con si sten cy checker, 

1300-1301 
creating, 1326-1327 
mounting/dismounting, 
802-804, 1328-1332 



msdos, 1125 
names, deleting, 882 
ncpfs, 1126 
nfs, 1125 

export list, 1123-1125 
proc, 1125 
quotas 

summarizing, 1376 
turni ng on/off, 
1372-1373 
repairing, 1298-1299 
Rock Ridge, 1125 
root, mounting, 849 
scanning, 1371-1372 
second extended 
checking, 1289-1291 
creating, 1324-1325 
lost+found directory, 1327 
tunable parameters 
(adjusting), 1412-1413 
setup, 849 
smb, 1126 
static information, 

1126-1127 
statistica getti ng, 883-884, 

865-866 
sysv, 1125 
tableof, 1427-1428 
type information, getting, 

871 
umsdos, 1125 
vfat, 1125 
xiafs, 1125 
filesystems command, 

1427-1428 
Altere 

Laplacian relief, runningon 

portable pixmaps, 413 
more, 327-328 

commands 328 

environment, 328 

options 327-328 
nonlinear (pnmnlfilt), 

390-391 
nroff output, 77 
reverse li ne feeds, 76 
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find, 137-142 

actions, 140-142 
expressions, 138 
numeric arguments, 

138-140 
operators, 142 
options, 138 
findaffix, 274, 280 
bugs, 282 
files, 281 
seeals) i speli 
finger daemons, configurable, 
1106-1109 
configuration file, 

1109-1115 
error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 
finger information, changing, 
60 

finite) ) function, 959 

first in - first out scheduling, 

833-834 
FITS files, convertingto 

portable anymaps, 142-143 
fitstopnm, 142-143 
floating-point numbers 
absolutevalue, 919 
converti ng 

to fracti onal/i ntegral 

componente 927 
to stringa 913-914, 
930-931 
extracting integrai and 
fractional values, 984 
multiplying, by integrai 
powers of 2, 961 
flock, 757 

floori ) function, 923 
floppy disks 

devices, 1080-1083 

configuration, 1080-1082 
drivers, boot-time 

parameters, 1223-1224 
formatting, 1295-1296 
marking bad blocks, 316 
parameters, setti ng, 1391 
fmod( ) function, 923 



fmt, 143 

fnmatch() function, 924 
fold, 143-144 
font files 

addingfont-metric 

information, 2 
creating, 3 
font formats 
converti ng 

Bitmap D i stri buti on to 
Portable C ompi led, 47 
packed format to portable 

bitmaps 381 
PostScript PFB format to 
ASCII, 369 
groffjont, 1127-1129 
DESC file 1127-1128 
font servers(X) 

displaying information 

about, 145 
generating BDF fonts, 

146-147 
listing fonts, 145-146 
fonts 
files, 1128 

creati ngfor groff, 513 
grops styles, 231-232 
man pages, 1247 
X 

displaying ali characters 

in, 633-636 
listing, 670-671 
X font server, 641-643, 689 
configuration, 642 
naming, 643 
fopen function, 924-925 
errors, 925 

modeargument sequences, 

924-925 
return values, 925 
fork, 758 

form (ftp command), 149 
formatting 

dates, strftimef ) function, 

1032-1034 
documents, gtroff, 237-248 
equations, 202-206 
floppy disks, 1295-1296 



input, 1013-1015 

conversions, 1014-1015 
flags, 1014 
line lengths, 143 
man pages, 1246-1248 
fonts 1247 
macros 1248 
preamble, 1246-1247 
sections, 1247-1248 
output, 992-996, 
1022-1023 
conversion specifiers. 994 
examples, 995 
flags 993-994 
technical papers 
groff_ me macros, 

1225-1227 
groff_mm macros 

1227-1234 
groff_ ms macros, 
1234-1236 
times, strftimef ) function, 

1032-1034 
trofftables, 236-237 
fpathconff ) function, 

925-926 
fprintf function, 992-996 
fpurge function, 920-921 
fputc( ) function, 997-999 
fputs( ) function, 997-999 
fractal forgeries, 404-407 
fread function, 926-927 
free, 144 

free( ) function, 976 
freopen function, 924-925 
frexp( ) function, 927 
fscanf function, 1013-1015 
fsck, 1298-1300 
fsck.minix, 1300-1301 
fseek function, 927-928 
fsetpos function, 927-928 
fsinfo, 145 
fslsfonts, 145-146 
fstab, 1126-1127 
file form at/options, 
1165-1167 



1454 



fiat 



fstat, 863-864 
fstatfs, 865-866 
fstobdf, 146-147 
fstopgm, 147 
fsync, 758-759 
ftell function, 927-928 
ftimefunction, 928-929 
ftok function, 929-930 

FTP (FileTransfer 
Protocol), DARPA server, 
1301-1304 
ftp, 147-154 

aborting transfer, 152 

bugs, 154 

commands, 148-152 
!, 148 
$, 148 
?, 152 

account, 148 
appena 1 , 148 
asci i , 148 
beli, 148 
binary, 148 
bye, 148 
case, 148 
ed, 148 
cdup, 148 
chmod, 148 
dose, 148 
cr, 148 
debug, 149 
delete 148 
dir, 149 
disconnect, 149 
form, 149 
gei, 149 
glob, 149 
hash, 149 
heJ p, 149 
idle 149 
Icd, 149 
Is, 149 
macdef, 149 
mdelete 149 
mdir, 150 
mget, 150 
mkdir, 150 



mls, 150 

mode, 150 

modtime, 150 

mput, 150 

ne/ver, 150 

nlii, 150 

nmap, 150 

ntrans 150-151 

open, 151 

prompt, 151 

proxyftp, 151 

put, 151 

pwd, 151 

quit, 151 

quote, 151 

rea/, 151 

reget, 151 

remotehelp, 151 

remotestatus, 151 

renarne, 151 

reset, 151 

reiart, 151 

rmdir, 152 

runique 152 

ssnd, 152 

sendport, 152 

a te, 152 

9'ze, 152 

iatus, 152 

struct, 152 

syiem, 152 

trace, 152 

type, 152 

umask, 152 

user, 152 

verbose, 152 
environment variables, 154 
filenamingconventions, 
153 

fi le transfer parameters, 153 
.netrc file, 153-154 
options, 147-148 
tenex, sendport, 152 
ftpd, 1301-1304 
bugs, 1303 

FTP requests supported, 

1302-1303 
options, 1302 



ftruncate* 879-880 
ftw( ) function, 930 
full-duplex connections, 

shutting down, 855 
function bindings, displaying, 

35 

functions 

calling at termination, 

897-898, 988 
headers, displaying, 455-456 
library, undocumented, 

1060 

portablepixmap programs, 
973-974 
color names 974 
memory management, 973 
readingfiles 974 
writingfiles, 974 
fuser, 154-155 
fwrite function, 926-927 

G 



g++, 155-160, 174-201 

bugs, 160 
copying, 160, 201 
filename suffixes, 174-175 
files, 159-160, 200 
options, 155-159, 175-178 
assembler, 181 
code generation, 198-199 
debugging, 186-187 
directory, 182-183 
language, 178-180 
linker, 181-182 
machine-dependent, 

191-198 
optimizatìon, 188-190 
preprocessor, 180-181 
target, 190-191 
warning, 183-186 
pragmas, 159, 200 
g3topbm, 160-161 
games, 1210 
gawk, 161-173 
actions, 165-166 
arithmetic functions, 
168-169 
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bugs, 172 

reporti ng, 172-173 
control statements, 167 
environment variables, 172 
fields, 163 
functions, 170 
GNU extensions, 171 
histori cai awk features 

supported, 172 
I/O statements, 167 
operators, 166-167 
options, 161-162 
patterns, 165-166 
POSIX compatibility, 171 
printf statement, 167-168 
program execution, 162-163 
regular expressions, 166 
special filenames, 168 
sprintf ( ) function, 167-168 
string constants, 169-170 
string functions, 169 
time functions, 169 
variables, 163-165 

arrays, 164 

built-in, 163-164 

typing and conversi on, 
164-165 
version information, 172 
gcal, 173-174 

running one day ahead, 506 
resourcefiles, creatingfrom 
textfiles, 558 
gcc, 174-201 

assembling output, 8-9 
bugs, 201 
copying, 201 

filename suffixes, 174-175 

files, 200 

options, 175-178 
assembler, 181 
codegeneration, 198-199 
debugging, 186-187 
directory, 182-183 
language, 178-180 
linker, 181-182 
machine-dependent, 
191-198 



optimization, 188-190 
preprocessor, 180-181 
target, 190-191 
warning, 183-186 
pragmas, 200 
gcvt( ) function, 930-931 
GEM IMG files, con vertingto 

portatile bitmaps, 201 
gemtopbm, 201 
GenerateM essagelD routine, 

964 
geqn, 202-206 

automatic spacing, 203 
bugs, 206 

customization, 204-205 
equation components, 

202-203 
files, 206 
fonts, 206 
macros, 206 

new primitives, 203-204 
options, 202 
get (ftp command), 149 
get current dir namef ) 

function, 931 
get_empty_filp, 1428 
get_ kernel, syms, 800-802 
getc( ) function, 945 
getchar( ) function, 945 
GetConfigValue routine, 965 
getcwd( ) function, 931 
getdents, 759 
getdirentries function, 

931-932 
getdomainname, 760 
getdtablesize, 760-761 
getegid, 761 
getenv( ) function, 932 
geteuid, 773 

GetFileConfigValue routine, 
965 

GetFQDN routine, 965 
getgid, 761 

getgrent( ) function, 932-933 
getgrgid( ) function, 933-934 
getgrnam( ) function, 933-934 
getgroups, 761-762 



gethostid, 762-763 
gethostname, 763 
getitimer, 763-764 
getlist, 206-207 
getlogin( ) function, 934-935 
getmntent( ) function, 

935- 936 

GetM oderatorAddress 

routine, 965 
getnetbyaddr subroutine, 

936- 937 
getnetbyname subroutine, 

936-937 
getnetent subroutine, 936-937 
getopt, 207-208 
getopt( ) function, 937-940 
environment variables, 939 
getopt_long( ) example, 

939-940 
return value, 939 
getopt long( ) function, 

938-940 
getopt long only( ) function, 
938 " 

getopts (shell command), 38 
getpagesize, 765 
getpass function, 940-941 
getpeername, 765 
getpgid, 845-846 
getpgrp, 845-846 
getpid, 766 
getppid, 766 
getpriority, 766-767 
getprotobyname( ) function, 

941-942 
getprotobynumberf ) 

function, 941-942 
getprotoentf ) function, 

941-942 
getpw( ) function, 942-943 
getpwent( ) function, 943 
getpwnam( ) function, 944 
getpwuid( ) function, 944 
GetResourceU sage routine, 

965 

getrlimit, 767-768 
getrusage, 767-768 
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gets( ) function, 945 
getservbyname( ) function, 
946 

getservbyport( ) function, 946 
getservent( ) function, 946 
getsid, 768 
getsockname, 769 
getsockopt, 769-772 

bugs, 772 

errors, 771 

options recognized, 770-771 
SO_BROADCAST, 771 
SO_DEBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO_KEEPALIVE, 770 
SO_LIN GER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIM EO, 771 
SO_REU SEAD D R, 770 
SO_SNDBUF, 771 
SO_SNDLOWAT, 771 
SO_SNDTIMEO, 771 
SO_TYPE, 771 
return value, 771 

GetTimel nfo routine, 965 

gettimeofday, 772-773 

getuid, 773 

getusershdl( ) function, 

946-947 
getutent( ) function, 947 
getutid( ) function, 947 
getutlinef ) function, 948 
getw function, 948 
getwd( ) function, 931 
GIF files, convertingto 

portableanymaps, 208-209 
giftopnm, 208-209 
giles, gpic, 215 
gindxbib, 209-210 
glob (ftp command), 149 
glob( ) function, 949-950 
glob dot filenamesvariable 

(ba~sh),17 
globfreef ) function, 949-950 



glookbib, 210 

gmtime, 984-986 

gmtimef ) function, 909-910 

gnroff, 210-211 

GNU linker, 287-291 

copying, 291 

environment, 291 

options, 288-291 
GNU ar, see ar 
GNU as, seeas 
GNU Bourne-again sheEI, see 
bash 

Gould scanner files, convert- 

ing to portable pixmaps, 211 
gouldtoppm, 211 
gpic, 211-215 

bugs, 215 

commands, 212-213 
expressions, 213-214 
file, 215 
mode, 212 
options, 211-212 
versus pie, 212-215 
gprof, 216-217 

graph profile data, displaying, 

216-217 
graphics (ASC 1 1 ), converting 

to portable graymap, 10 
graphs 

system load average, 533 
topological sorts, 542 
grayscale ramps, generating, 

374-375 
greaterthan signs (>), 

redirection operator, 21 
grefer, 217-224 

bibliographic databases, 219 
bugs, 224 
citations, 219-220 
commands, 220-222 
files, 224 

label expressions, 223-224 
macro interface, 224 
options, 218-219 



grep, 224-226 

bugs, 226 

diagnostics, 226 

options, 224-225 

regular expressions, 225-226 
grodvi, 227-228 
groff, 228-230 

availability, 230 

bugs, 230 

creating font files for, 513 
environment, 229 
files, 229 

guessing options, 230 
interpreting .so requests, 

236 
options, 229 

output, converting to TeX 
dvi format, 227-228 

PostScript driver, 230-235 

preprocessing references, 
217-224 

typewriter device driver, 235 
groff font format, 1127-1129 

DE SC file, 1127-1128 
groff me, 1225-1227 
groff mm, 1227-1234 

extensions, 1227-1229 

number variables, 
1233-1234 

strings, 1233 

variables, 1229-1230 
groff ms, 1234-1236 
groff out, 1129-1131 
grog, 230 
grops, 230-235 

files, 234 

font styles, 231-232 

options, 231 

X commands, 232-233 
grotty, 235-236 
group, 1131 

Group 3 fax files, converting 

to portable bitmaps, 

160-161 
group access lists 

getting/setting, 761-762 
initializing, 955 



HISTSIZE variable(bash) 
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group fileentries, getting, 

921-922, 932-934 
group identity, setting, 845 
group IDs 

getti ng/setting, 761, 

845- 846 

real and effettive, setting, 

846- 847 

group ownership (files), 

changing, 61 
groups 

addingto system, 

1258-1259 
logging into, 336-337 
process, sending signalsto, 
960 

grow files, 1428-1429 
grttoppm, 436-437 
gsoelim, 236 
gtbl, 236-237 
gtroff, 237-248 

environment, 248 

escape sequences, 239-240 

files, 248 

fractional pointsizes, 238- 
239 

incompatibilities, 247-248 

long names, 238 

numericexpressions, 239 

options, 238 

requests, 241-244 
extended, 244 
number registers. 245-246 

warnings, 246-247 
gunzip, 248-249 

seealso gzip 
gzexe, 252-253 
gzip, 248-252 

bugs, 252 

diagnostics, 251-252 
environment, 251 
options, 249-250 
gzip files, forcing .gz exten- 
sion, 732-733 



H 



handling signals, 857-858 
hard disks 

boot-timeparameters, 

1220-1221 
devices, 1083 

partition tables, manipulat- 
ing, 1296-1297 
hard drives, partitioning, 

1265-1269 
hard-reset( ) action (xterm), 
715 

hardware, video (identifying), 

501-503 
hash 

ftp command, 149 

shell command, 38 
hash tables 

creating, 951 

freeing memory, 951 

searching, 951 
hasmntopt( ) function, 

935-936 
hcreate( ) function, 951-952 
hd, 1083 

hdestroy( ) function, 951 
head, 253-254 
HeaderCleanFrom routine, 
964 

HeaderFind routine, 964 
headers function, displaying, 

455-456 
help 

ftp command, 149 
shell command, 38 
xauth command, 591 
here-documents, 22-23 
hexdump, 254-256 
hier, 1236-1238 

directories, 1236-1238 
/, 1236 
/bin, 1236 
/boot, 1236 
/de/, 1236 
/dos 1236 
/etc, 1236 



/etc/ska , 1236 
/etc/Xll, 1236 
/home, 1236 
/lib, 1236 
/mnt, 1236 
/proc, 1236 
/sbin, 1237 
/tmp, 1237 
/us-, 1237 
/U3-/X11R6, 1237 
/usr/XHR6/bin, 1237 
/us7XHR6/lib, 1237 
/usr/XHR6/lib/Xll, 1237 
/us-XllR6/ìndude/Xll, 
1237 
hierarchies 

directory (creating), 323 
filesystem, description of, 
1236-1238 
H igh Sierra filesystem, 1125 
H I PS files, converting to 
portable graymaps, 256 
hipstopgm, 256 
histchars variable (bash), 
17-18 

HISTCMD variable (bash), 
16 

H I ST FILE variable (bash), 17 
HISTFILESIZE variable 

(bash), 17 
histograms 

drawingfor PGM or PPM 

files, 388 
portable pixmaps, printing, 

408 

history, 1131-1132 

control variable (bash), 17 

cvs command, 99 

shell command, 39 
history expansion (bash), 
33-34 

event designators, 33 

modifiers, 34 

word designators, 33 
history lists (bash), 32-33 

displaying, 39 
HISTSIZE variable (bash), 17 



1458 



HOME vari able ( bash) 



HOME variable (basti), 16 
/home directory, 1236 
horizontal-scroll-mode 
variable (readline), 28 
host, 257-258 
bugs, 258 
customizing, 258 
options, 257-258 
host byte order, converting 
between network byte order, 
901-902 
host I D s, printing, 258-259 
hostid, 258-259 
hostname, 259-260, 

1238-1239 
hostnamecompletionfile 

variable (bash), 18 
hostnames 

displaying, 259-260 
looking up, 257-258 
resolving, 1238-1239 
hosts 

identifiers, getti ng/setting, 
762-763 

names, getting/setting, 763 

sending messages to users 
on, 473 
hosts.nntp, 1132-1133 
hosts.nntp.nolimit, 

1132-1133 
hosts_ access, 1133-1136 

access control files, 1133 

access control rules, 1133 

bugs, 1136 

diagnostics, 1136 

files, 1136 

operators, 1134 

patterns, 1133-1134 

remote username lookup, 
1134-1135 

shell commands, 1134 

wildcards, 1134 
hosts access( ) function, 

950~951 
hosts. ctl( ) function, 950-951 
hosts. options, 1137-1139 

diagnostics, 1139 

options, 1137 



HOSTTYPE variable (bash), 
16 

H P PaintJet files, converting 

to portable pixmaps, 381 
hpcdtoppm, 260-261 
hpfsfilesystem, 1125 
hsearchf ) function, 951-952 
htonl( ) function, 901-902 
htonsf ) function, 901-902 
httpd, 261 

hyperbolic cosines, 908 
hyphens (-), bash special 

parameters, 15 
hypotf ) function, 953 

I 



I/O 

awk statement, 167 
port permissions, setting, 
788 

ports, functions, 816 

privilegelevel, changing, 
788-789 

standard I/O library, 
1025-1027 
ICCcancel routine, 956 
ICC dose routine, 956 
ICCcommand routine, 956 
ICC open routine, 956 
ICC pause routine, 956 
ICC reserve routine, 956 
ICCsettimeout routine, 956 
icombine, 274, 281 

files, 281 

seealso ispell 
icontopbm, 262 
ident, 262-263 
idle, 774 

errors, 774 

ftp command, 149 

return value, 774 
I D s (group), searching for 

matches, 1429 
$if parser direttive (readline), 

28-29 
ifconfig, 1304-1305 



IFS variable (bash), 16 
ignoref ) action (xterm), 713 
IGNOREEOF variable (bash), 
17 

ijoin, 274, 281 
files, 281 
seealso ispell 
ILBM files, converting to 

portable pixmaps, 263-264 
ilbmtoppm, 263-264 
image files, converting to 

portable anymap, 4 
image parameter, values, 1374 
imake, 264-267 

environment variables, 267 
files, 266 

input, 266 
options, 265 
X Window System, 266 
Imakefiles, creati ng Makefiles 

from, 672 
Img-whatnot file, converting 

to portable pixmaps, 267 
imgtoppm, 267 
import ( cvs command), 100 
in group p, 1429 
inb, 816 
inb p, 816 

inbound zonetransfers, 

1333-1334 
index( ) function, 953 
indexes, archives (generati ng 

for), 437-438 
inet addr( ) function, 954 
inet aton( ) function, 954 
inet_lnaof( ) function, 954 
inet makeaddr( ) function, 

954 

inet netof( ) function, 954 
inet network( ) function, 954 
inet ntoa( ) function, 954 
inetd, 1305-1307 
inews, 267-269 
infinite results 

returning valuefor, 954-955 

testingfor, 959 
infnan( ) function, 954-955 
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info, 269-270 

commands, 269-270 

environment, 270 

options, 269 
info command (xauth), 591 
init, 1307-1309 

diagnostica, 1309 

files, 1308 

run levels, 1308 
initmodule, 800-802 
init_ timer, 1424 
initgroups( ) function, 955 
initializing 

terminals, 539-542 

X sessions, 496-497 
initstate( ) function, 

1001-1002 
inittab, 1139-1141 
inittab file, 1398 
ini, 816 
ini p, 816 
inn.conf, 1141-1142 
innconfval, 270-271 
innd, 1309-1312 

control messages, 1310 

header modifications, 1311 

logging, 1311-1312 

protocol differences, 
1310-1311 
inndcomm routines, 956 
inndstart, 1309-1312 
INNVersion routine, 966 
innwatch.ctl, 1142-1144 
innxmit, 1312-1313 
input 

formatti ng, 1013-1015 
conversions 1014-1015 
flags 1014 

reading, 27-32 

control I i ng key bindings 
27 

denoting ke/strokes, 27 
macro definiti ons, 28 
readlinecommands, 
29-32 
redirecting, 22 



input lines, wrapping, 143- 

144 
input, seeel vis 

INPUTRC variatale (bash), 17 
insb, 816 

inserti ) action (xterm), 713 
insert-eight-bit( ) action 

(xterm), 713 
insert-selection( ) action 

(xterm), 713 
insert-seven-bit( ) action 

(xterm), 713 
insert file free, 1429 
insl, 8~16 " 
insmod, 271-272 
insque( ) function, 957 
instali, 272-273 
installing 

loadablemodules, 271-272 
rstartd, 469 
spottopgm, 495 
sysklogd, 1403 
installit, 273-274 
insw, 816 
integers 

absolutevalues, 892-893 
converti ng, between host 
and network byteorder, 
901-902 
dividing, 911 

floating-point remainders, 

913,923 
returning quoti ent and 
remainder, 961 
long, labs, 960-961 
rounding, 904 
downward, 923 
to, 1011-1012 
interactive shells, 45 
interfaces 

namedaemon control, 

1338-1339 
network 

attachi ng to seri al line 
1399 

confi guring, 1304-1305 



serial mouse, 1092-1094 
M i crosoft protocol, 1093 
M M protocol, 1094 
M ouseSystems protocol, 

1093 
Sun protocol, 1093 
interned atoms, listing, 

668-669 
Internet 

addresses, manipulating, 

953-954 
extended I nternet services 

daemon, 655-664 
inetd superserver, 

1305-1307 
services, listing, 1184-1186 
InterN etN ews 

buffered fi le-writi ng, 1264- 

1265 
configuration data, 

1141-1142 
daemon, 1309-1312 
control messages 1310 
controlling, 1276-1279 
file-writing, 1297-1298 
InterN etN ews library 
clientlib, 904-905 
INND communication 

routi nes, 956 
libinn routines, 962-966 
CAclose, 964 
CAIistopen, 964 
CAopen, 964 
CloseOnExec, 965 
D D check, 965 
DDend, 965 
DD start, 965 
GetConfigValue, 965 
GetFileConfigValue, 965 
GetFQDN, 965 
GetM oderatorAddress, 
965 

GetResourceU sage 965 
GetTimelnfo, 965 
HeaderFind, 964 
INNVersion, 966 
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LockFìle, 965 
NNTPcheckartide, 965 
NNTPconnect, 965 
N N T Plocalopen, 965 
N NTPremoteopen, 965 
N NTPsendarticle, 966 
N NTPsendpassword, 966 
Radìx32, 966 
Readln Decriptar, 966 
ReadlnFile, 966 
SetNonBlocking, 965 
Quick I/O, 998 
interrupt key sequence, 

routing, 1425 
interval timers 

getting/setting value, 

763-764 
ITIM ER_PROF, 764 
ITIM ER_REAL, 764 
ITIM ER_VIRTUAL, 764 
value definitions, 764 
inverse hyperbolic cosines, 

893-894 
inverse hyperbolic sines, 895 
inverse hyperbolic tangents, 
897 

inverted indexes, biblio- 

graphic databases, 209-210 
invocation, bash, 45-46 
inw, 816 
inw p, 816 
iocti, 774-788 

arguments, 787-788 

calls 

consles 1074-1080 

fd devicesupport, 1082 

liiof, 775-786 

Ip, 1090-1091 

sd, 1095-1096 

st, 1097-1100 
duplicates, 788 
errors, 774 
return value, 774 
ioperm, 788 
iopl, 788-789 
errors, 789 
return value, 789 



IP 

dialup connections, handler, 

1285-1288 
routing table (manipulat- 

ing), 1379-1380 
ipc, 789, 1144-1146 
messagequeues, 1145 
resource access permissions, 

1144-1145 
semaphoresets, 1145-1146 
shared memory segments, 

1146 
ipc facilities 

getting information on, 

1314 

removing, 1313-1314 
IPC system calls, 789 
ipcrm, 1313-1314 
ipcrs, 1314 

isalnumf ) function, 958 
isalpha( ) function, 958 
isascii( ) function, 958 
isatty function, 958-959 
isblankf ) function, 958 
iscntrl( ) function, 958 
isdigitf ) function, 958 
isgraph( ) function, 958 
isinf( ) function, 959 
islower( ) function, 958 
isnan( ) function, 959 
ISO character sets 

2022, 1066 

4873, 1066 

8859, 1064-1065 

8859-1, 1239-1242 
alphabets. 1240 
characters, 1240-1242 
iso9660 filesystem, 1125 
ispell, 274-279, 1084-1090 

affixfile, 1084-1085 

alternate string characters, 
1087 

bugs, 282 

capital ization rules, 279 
character-set section, 1086 
commands, 274-275 
flags, 1088 



headers, 1085 
options, 275-279 
optionsstatements, 

1085-1086 
prefix/suffix tables, 1088 
root words 
case, 1084 
extending, 1085 
modifying, 1088-1089 
isprintf ) function, 958 
ispunct( ) function, 958 
isspace( ) function, 958 
issue, 1146-1147 
isupper( ) function, 958 
isxdigitf ) function, 958 
ITIM ER PROF interval 

timer, 764 
ITIM ER RE AL interval 

timer, 764 
ITIM ER VIRTUAL interval 
timer, 764 

J 



jO( ) function, 959 
jl( ) function, 959 
jn( ) function, 959 
job control, 24-25 
jobs, displaying, 39 
jobs (shell command), 39 
join, 282-283 
jrand48( ) functions, 912 

K 



kbdrate, 1314-1315 
Kerberosauthentication, 461 
kernel 

boot-timeparameters, 
1216-1224 
Adaptec confi gurations. 

1219-1220 
argument list, 1216-1217 
BusLogic confi gu rati on, 
1220 

busmousedrivers, 1224 
cardsnot accepting, 1220 
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CD-ROMs 1222-1223 
debug argument, 1217 
Ethernet devices, 1223 
floppy disk d ri vers, 

1223-1224 
future domain configura- 
ti on, 1220 
harddisks, 1220-1221 
mem= argument, 1218 
no- hit argument, 1217 
no387 argument, 1217 
Pro Audio confi guration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 

1218 
reserve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI devicearguments, 

1218- 1219 

SCSI tape confi guration, 

1219 
SeagateST-Ox 

confi guration, 1220 
sound drivers, 1224 
TrantorT128 
confi guration, 1220 
exported symbols, display- 

ing, 284-285 
log buffer, 873 
message ring buffer, reading/ 

clearing, 872-874 
modules, loading at boot 

time, 1152 
name, getti ng, 880-881 
ring buffer, controlling, 
1288-1289 
kernel clock, adjustlng, 

742-743 
kernel log daemon, 

1315-1317 
kernel logglng, 1402 
kernelmktime, 1430 
key bindings, displaying, 35 



key combinations, 
Ctrl+Alt+Dd {setting 
function), 1279 
key sequences (interrupt), 

routing, 1425 
keyboard repeat rate, 
resetting, 1314-1315 
keymap variable (readline), 28 
keymapf ) action (xterm), 713 
keymaps(X), modifying, 

672-676 
keywords, RCS, identifying in 

files, 262-263 
kill, 283-284, 790 
bugs, 790 
errors, 790 
options, 283 
return value, 790 
shell command, 39 
killall, 284 

killing client connections (X 

servers), 666-667 
killpg, 790-791, 960 
klogd, 1315-1317 

files, 1317 
options, 1315 

signal handling, 1316-1317 
kmem, 1091-1092 
KOI8-R character set, 1065 
ksyms, 284-285 

L 



labs( ) function, 960-961 
Laplacian rdief filters, 

runningon portable 

pixmaps, 413 
last, 285-286 

Latin-1 character set, 1064 
Latin-2 character set, 1064 
Latin-3 character set, 1064 
Latin-4 character set, 1064 
Latin-5 character set, 1065 
Latin-6 character set, 1065 
Ibxproxy, 286-287 

network connections, 286 

options, 286 



Icd (ftp command), 149 
lcong48( ) functions, 912 
Id, 287-291 

copying, 291 

environment, 291 

options, 288-291 
ldexp( ) function, 961 
ldiv( ) function, 961 
lessthan signs(<), redirection 

operator, 21 
let (shell command), 39 
letters, converting 

tolowercase, 1055-1056 

to uppercase, 1055-1056 
lfind( ) function, 975-976 
lgamma( ) function, 962 
/lib directory, 1236 
libinn routines, 962-966 

CAclose, 964 

CAIistopen, 964 

CAopen, 964 

CloseOnExec, 965 

DD check, 965 

DDend, 965 

DD start, 965 

GetConfigValue, 965 

GetFileConfigValue, 965 

GetFQDN, 965 

GetM oderatorAddress, 965 

GetResourceUsage, 965 

GetTimelnfo, 965 

HeaderFind, 964 

INNVersion, 966 

LockFile, 965 

NNTPcheckarticle, 965 

NNTPconnect, 965 

NNTPIocalopen, 965 

N NTPremoteopen, 965 

NNTPsendarticle, 966 

N N T Psendpassword, 966 

Radix32, 966 

Readl nD escri ptor, 966 

ReadlnFile, 966 

SetNonBlocking, 965 
libpbm routines, 966-969 

constants, 968 

endian i/o, 967 

errors, 967 
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file management, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 
readingfiles, 968 
types, 968 

writingfiles, 968-969 
libpgm routine, 969-970 

constants, 969 
initialization, 969 
memory management, 969 
readingfiles, 970 
types, 969 
writingfiles, 970 
libpnm routine, 970-972 
constants, 970 
format promotion, 972 
initialization, 971 
memory management, 971 
readingfiles, 971 
types, 970 

writingfiles, 971-972 
XEL manipulation, 972 
XEL manipulations, 971 
libppm, 973-974 
color names, 974 
memory management, 973 
readingfiles, 974 
writingfiles, 974 
librarie 

shared, selecting, 883 
standard I/O , 1025-1027 
library functions, undocu- 

mented, 1060 
LILO, 1216 

conf iguration file, 
1147-1151 
global options, 1148-1149 
kernel options, 1150-1151 
per-imagesection, 
1149-1150 
linebuffered streams, 1016 
line printer 

control program, 1317-1318 
devices, 1090-1091 

ioctIO calls 1090-1091 
spoolerdaemon, 1318-1320 



linear searches, arrays, 

975-976 
LINENO variatale (bash), 15 
link, 791-792 
linkers, Id (GNU linker), 
287-291 
copying, 291 
environment, 291 
options, 288-291 
linking files, 293-294, 791- 
792 

Lisp M achine bitmap file, 
converting to portatale 
graymaps, 292 

lispmtopgm, 292 

list 

bash command, 13 

xauth command, 591 
listen, 792-793 
liste 

bash, 12-13 

columnating, 78 

variableargument (declar- 
ing), 1023-1024 
Ikbib, 292-293 
llseek, 793 
In, 293-294 
Indir, 294 
loadablemodule 

installing, 271-272 

support, 800-802 

unloading, 462-463 

viewing, 305 
loadlin program, 1216 
locai (shell command), 39 
locai descriptor table, reading/ 

writing, 800 
locai variables, creating, 39 
locale, 1243-1244 

setting, 1018-1019 
localeconv, 974-975 
localtime, 909-910, 984-986 
locate, 295 

lock file creating for shell 

scripts, 487 
LockFile routine, 965 



locking memory 

mlock, 796-797 
mlockall, 797-798 
locks (advisory), applying/ 
removing open file, 757 
log (cvs command), 100 
log( ) function, 918 
Iogl0( ) function, 918 
loglp( ) function, 918 
logarithms, 918 
1 plusargument, 918 
base-10, 918 
logger, 295-296 
logging 

innd, 1311-1312 
kernel, 1402 
system, 1402-1404 
configuration file 

1402-1403 
FIFOs, 1403 
messages» 1404-1405 
remote, 1403 
Usenet, log file 
maintenance, 1346-1347 
login, 296-297 
login shdls, 45 
changing, 63 
exiting, 39 
logins 

changing groups, 336-337 
displaying last, 285-286 
login command, 296-297 
login record files, 

1198-1200 
preventing, 1168 
remote, 460-461 

Kerberos authentication, 
461 

root, tty lines (listing), 1184 
shells, pathnames, 1186 

logout (shell command), 39 

logs 

system 

making entri es, 295-296 
sending messages to, 
1045-1046 

xinetd, 661-663 
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long integers, absolute values, 

960-961 
longjmp( ) function, 975 
look, 297-298 
loops 
exiting, 35 
resuming, 36 
lowercase, converting letters 

to, 1055-1056 
Ip, 1090-1091 

Ip devices, setting parameters, 

1413-1414 
Ipc, 1317-1318 

commands, 1317-1318 

diagnostica 1318 
Ipd, 1318-1320 

key characters, 1319 

options, 1319 
Ipq, 298-299 

bugs, 299 

diagnostica 299 

environment, 299 

options, 298-299 
Ipr, 299-301 

bugs, 301 

diagnostica 301 

environment, 300 

options, 299-300 
Iprm, 301-302 

bugs, 302 

diagnostica 302 

environment, 302 

options, 301 
Iptest, 302 

Irand48( ) functions, 912 

Is, 303-304 

Es (ftp command), 149 

Isattr, 304-305 

Isearchf ) function, 975-976 

Iseek, 793-794 

Ismod, 305 

Istat, 863-864 

lynx, 306-309 

commands, 308-309 

options, 306-308 



M 



macdef (ftp command), 149 
Macintosh PICT files, 

converting to portatile 

pixmaps, 379-380 
M acPaint files, converting to 

portatile bitmaps, 309-310 
macptopbm, 309-310 
magic cookies, generating, 

317 

mail addressing, 1244-1246 

abbreviations, 1245 

case sensitivity, 1245 

compatibility, 1245 

postmasters, 1246 

routing, 1245 
mail, see e-mail 
MAIL variatile (basii), 16 
MAIL WARNING variable 

(basti), 16 
mailaddr, 1244-1246 

abbreviations, 1245 

bugs, 1246 

case sensitivity, 1245 

compatibility, 1245 

postmasters, 1246 

routing, 1245 
MAILCHECK variable (basti), 
16 

MAILER environment 

variable, 529 
MAILPATH variable (bash), 

16 

make, 310-312 

imake preprocessor, 264-267 

options, 311 
makeactive, 1342-1344 
makedepend, 312-314 

algorithm, 313 

bugs, 314 

options, 312-313 
MAKEDEV, 1320-1324 

files, 1321 

options, 1321-1324 
MAKEDEV.cfg, 1151 



makefiles 

creating dependencies in, 

312-314 
creating from I makefiles, 

672 

makehistory, 1342-1344 
makestrs, 314-315 

bugs, 315 

directives, 315 

options, 314 

syntax, 314-315 
malloc( ) function, 976 
man, 1246-1248 
man pages, formatti ng, 
1246-1248 

fonts, 1247 

macros, 1248 

preamble, 1246-1247 

sections, 1247-1248 
mapping files to memory, 

799-800 
mark-modified-lines variable 

(readline), 28 
mask bitmaps, creating from 

regular, 353-354 
masks, file-creation, 880 

setting, 45 
mattrib, 315-316, 330 
mbadblocks, 316, 330 
mblen, 977 
mbstowcs( ) function, 

977- 978 

mbtowc( ) function, 978 
mcd, 316-317, 330 
mcookie, 317 
mcopy, 317-318, 330 
M D 5 message digests, 

generating/ checking, 318 
md5sum, 318 
mdel, 318-319, 330 
mdelete(ftp command), 149 
mdeltree, 319 
mdir, 150, 319, 330 
mem, 1091-1092 
memccpy( ) function, 901, 

978- 979 

memchrf ) function, 901, 979 
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memcmpl ) function, 901, 

979- 980 

memcpyl ) function, 901, 980 
memfrob( ) function, 901, 

980- 981 

memmemf ) function, 901, 
981 

memmove( ) function, 901, 

981 
memory 

access, controlling, 804-805 

allocating, 894, 976 

displaying amount, 144 

freeing, 976 

kernel, 1091-1092 

locking 

mlock, 796-797 
mlockall, 797-798 

mapping/unmapping files 
to, 799-800 

reallocating, 976 

scanning for characters, 979 

shared 

allocating, 851-853 
controlling, 849-851 
operati ons, 853-854 

system, 1091-1092 

unlocking 

munlock, 811-812 
munlockall, 812-813 

virtual 

remapping addresses, 

805-806 
reports, 1417-1418 

virtual console, 1101-1102 
memory areas 

comparing, 979-980 

copying, 978-981 

encrypting, 980-981 

fi II ing with Constant bytes, 
982 

locating substrings in, 981 
memsetf ) function, 901, 982 
merge, 320 

mergecommand (xauth), 591 
merging files, three-way, 320 
mesg, 321 



message catalogs 

getting messages from, 

902-903 
opening/closing, 903-904 
message queue i dentiti er, 

retrieving, 807-808 
messages 
control, 1310 

control operations, 806-807 

displaying, 321 

log (RC S files), printing, 

458-460 
message of the day file, 1152 
reca ving, from sockets, 

826-828 
sending/receiving, 808-811 
sending 

from sockets 842-843 
to system logger, 

1045-1046 
tousers, 473, 576-577 
signal, printing, 996 
system console, monitoring 

with X, 597-598 
system error, printing, 

990-991 
systems, logging, 1404-1405 
Usenet control, handling, 

1115-1116 
writing to users, 574, 1383 
meta characters (basii), 12 
meta-flag variable (readline), 
28 

mformat, 321-322, 330 

bugs, 322 

options, 321-322 
mget (ftp command), 150 
M G R bitmaps, converting to 
portable bitmaps, 322-323 
mgrtopbm, 322-323 
MIN IX filesystems, 1125 

consistency checker, 
1300-1301 

creating, 1326-1327 
mkdir, 150, 323, 794-795 

bugs, 795 

errors, 795 



options, 323 

return value, 795 
mkdirhier, 323 
mke2fs, 1324-1325 
mkfifo, 323-324, 982-983 

errors, 982-983 

options, 324 
mkfs, 1325-1327 
mklost+found, 1327 
mkmanifest, 324-325 
mknod, 325, 795-796 

bugs, 796 

errors, 796 

options, 325 

return value, 796 
mkstemp( ) function, 983 
mkswap, 1327-1328 
mktemp( ) function, 983-984 
mktime, 910, 984-986 
mlabel, 325-326, 330 
mlock, 796-797 
mlockall, 797-798 
mls (ftp command), 150 
mmap, 799-800 
mmd, 326, 330 
mmount, 326-327, 330 
mmove, 327, 330 
/mnt directory, 1236 
mode (ftp command), 150 
mode command (telnet), 508 
mode parameter, values, 1374 
modems, conversational 
exchanges, 1269-1273 

abort strings, 1270-1271 

chat script, 1270 

escape sequences, 
1271-1272 

report strings, 1271 

termi nation codes, 1272 

time-out value, 1271 
moderators, 1151-1152 
modf( ) function, 984 
modifyjdt, 800 
modprobe, 109-112 

configuration, 110-111 

files, 111 

strategy, 111 
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modtime (ftp command), 150 
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named, 1334-1338 

boot file, 1334-1336 

film 1337 

master file, 1336 

options, 1334 

signals, 1337 

SO A record, 1336-1337 
named pipes, seeFIFOs 
named-xfer, 1333-1334 
named. reload, 1338 
named. restart, 1338 
namei, 335-336 

options, 336 

output, 335 
names 

bash, 12 

peer, getti ng, 765 

socket, getting, 769 
nameserver (Internet 
domains), 1334-1338 

boot file, 1334-1336 

control interface, 1338-1339 

master file, 1336 

querying, 1350-1353 

signals, 1337 

SO A record, 1336-1337 

stoppi ng/restarting, 1338 

synchronizing database, 
1338 
naming 

font servers, 643 

temporary files, 1049, 1054 

xhost, 644 
NaN (not-a-number) results 

returning valuefor, 954-955 

testingfor, 959 
nanosleep, 813-814 
ncpfsfilesystem, 1126 
ndc, 1338-1339 
N etnews reader, see tin 
.netrcfìle, 153-154 
netstat, 1339-1342 

files, 1341 

routing information, 1341 
socket information, 
1340-1341 



network byte order, convert- 
ing between host byte order, 
901-902 
network entries, getting, 

936-937 
networking 
displaying active 
connections, 1339-1342 
routing information, 1341 
socket information, 
1340-1341 
interfaces 

attachi ng to seri al line 
1399 

confi gurìng, 1304-1305 
routing daemon, 1380-1382 
newaliases, 336 
newer (ftp command), 150 
newgrp, 336-337 
news 

N etnews, see tin 

news software information 

newsgroups, 530 
overview database 
expiring entries 

1293-1294 
format, 1168-1169 
updatìng, 1353-1354 
receivingfrom UUCP 
connections, 463-464 
news.daily, 1344-1346 
keywords, 1344-1345 
newsfeeds, 1158-1163 
Distribution headers, 1159 
entries, 1158-1159 
examples, 1162-1163 
feed types, 1161-1162 
flags, 1159-1161 
M E entry, 1161 
newsgroups 

news software information, 
530 

Usenet, listi ng active, 1104- 
1105 

newslog, 1163-1165, 
1346-1347 

files, 1164 
keywords, 1346 
message/ action fields, 



1163-1164 
newsrequeue, 1342-1344 
NFS 

mount daemon, 1332-1333 

servers, authentication/print 
request, 1355-1357 

service daemon, 1347 
nfs, 1165-1167 
nfsfilesystem, 1125 

export list, 1123-1125 
NFS servers, mount 
information, 1396 
nfsd, 1347 
nice, 814 
ni, 337-338 

nlist (ftp command), 150 
NLM outfiles, converting 

object code into, 338-339 
nlmconv, 338-339 
nm, 339-340 

nmap (ftp command), 150 
nnrp.access, 1167-1168 
nnrpd, 1347-1349 
NNTP 

news, host list, 1132-1133 
servers, 1347-1349 

getting li isfrom, 206-207 
password^ 1170 
retri evi ng Usenet arti ci es 
from, 340-341 
sites, access control, 
1167-1168 
NNTPcheckarticle routine, 
965 

NNTPconnect routine, 965 
nntpget, 340-341 
NNTPIocalopen routine, 965 
NNTPremoteopen routine, 
965 

nntpsend, 1349-1350 
nntpsend.ctl, 1168 
NNTPsendarticle routine, 966 
NNTPsendpassword routine, 
966 

NNTPSERVER environment 
variable, 529 
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no_exit_on_failed_exec 

variatile (basii), 18 
noclobber variable(bash), 18 
noi inks variatale (bash), 18 
nologin, 1168 
none, 881 

none (undocumented library 

functions), 1060 
not-a-number (N aN ) results 

returning valuefor, 954-955 
testing for, 959 
notify variatale (bash), 17 
nrand48( ) functions, 912 
nroff 

emulating, 210-211 
output, fi Iteri ng, 77 
nslookup, 1350-1353 
arguments, 1350 
commands, 1351-1353 
diagnostica, 1353 
environment, 1353 
files, 1353 
ntohl( ) functìon, 901-902 
ntohs( ) function, 901-902 
ntrans (ftp command), 

150-151 
nuli, 1094 
numbers 
floating-point 
absolute value, 919 
converting to fractional/ 
integrai components, 
927 

converting to stringa 
913-914, 930-931 
pseudo-random, generating, 

912-913 
random, generating, 

1001-1002 
rounding, 1011-1012 
signs, copying, 907 
square roots, 1023 
numeric expressions, gtroff, 
239 
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objcopy, 341-342 
objdump, 342-343 
object files 

copying/translating, 

341- 342 
discarding symbols from, 

499 

displaying information from, 

342- 343 

listing section and total sizes, 

489-490 
listing symbols from, 
339-340 
oclock, 344 
od, 345-346 

offline printing, 299-301 
oldfstat, 814 
oldlstat, 814 
oldolduname, 814 
OLDPWD variatale (bash), 15 
oldstat, 814 
olduname, 814 
on_exit( ) function, 988 
open, 815-816 

bugs, 816 

errors, 816 

flags, 815 

ftp command, 151 

modes, 815 

return value, 816 
open host command (telnet), 

508 
opendir, 989 
openlog( ) function, 
1045-1046 

facility argument, 1046 

option argument, 1046 
operators 

awk, 166-167 

find, 142 

redirection, 21 
OPTARG variatale (bash), 16 
O PT E R R variatale (bash ), 17 
OPTIND variatale (bash), 16 



ORGANIZATION environ- 
ment variatale, 529 
OSTYPE variatale (bash), 16 
outb, 816 
outb_p, 816 
outl,816 
outl_p, 816 
output 

formatting, 992-996, 
1022-1023 
conversion specifiers 994 
examples, 995 
flags 993-994 
redirecting, 22 
output-meta variatale 

(readline), 28 
outsb, 816 
outsl, 816 
outsw, 816 
outw, 816 
outw p, 816 
overchan, 1353-1354 
overview.fmt, 1168-1169 
ownership (file), changing, 
62-63, 749-750 
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pac, 1354-1355 
packed format fonts, convert- 
ing to portatale bitmaps, 381 
packets 

ECH 0_REQ U EST, 

sending, 1358 
route, printing, 1409-1412 
page si ze, system (getting), 

765 
paging 

disabling, 796-797 

calling process, 797-798 
reenabling, 811-813 
papers, formatting 
groff_memacros, 

1225-1227 
groff_mm macros, 

1227-1234 
groff_ms macros, 
1234-1236 
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paragraphs, formatti ng line 

length, 143 
parameter command substitu- 

tion (bash), 20 
parameter expansion (bash), 

19-20 
parameters 
bash, 14-15 
pog'tional, 14 
spedai, 14-15 
boot-time (kernel), 
1216-1224 
Adaptec confi gu rations, 

1219-1220 
argument list, 1216-1217 
BusLogic confi guration, 
1220 

busmousedrivers 1224 
cardsnot accepting, 1220 
CD-ROMs 1222-1223 
debug argument, 1217 
Ethernet da/ices, 1223 
floppy disk drives, 

1223-1224 
future domain 

confi guration, 1220 
hard disks, 1220-1221 
mem= argument, 1218 
no- hit argument, 1217 
no387 argument, 1217 
Pro Audio confi guration, 

1220 

ramdisk= argument, 1218 
reboot=warm argument, 

1218 
reserve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI da/icearguments, 

1218- 1219 

SCSI tape confi guration, 

1219 
SeagateST-Ox 

confi guration, 1220 



sound drivers 1224 
TrantorT128 
con fi guration, 1220 
floppy disk, setting, 1391 
positional 
parsi ng, 38 
renami ng, 42 
serial ports, 1392-1394 
parsedate, 989-990 
parser directives, readline, 
28-29 
$else, 29 
$endif, 29 
$if, 28-29 
parsing 

command options, 207-208 
command-lineoptions, 

937-940 
positional parameters, 38 
partition tables, manipulat- 
ing, 1296-1297 
DOS6.X, 1296-1297 
partitioning disk drives, 

1265-1269 
passwd, 346-347, 1169-1170 
bugs, 347 
files, 347 
passwd.nntp, 1170 
password files, editing, 

1418-1419 
passwords 

changing, 346-347 
encryption, 908-909 
fileentries, writing, 997 
getti ng, 940-941 
getting file entry, 943-944 
password file, 1169-1170 
reconstructing line entry, 
942-943 
paste, 347 

PATH variatale (bash), 16 
pathconf( ) function, 925-926 

options returned, 926 
return value, 926 
pattinarne expansion (bash), 
21 



pathnames 

canoni cai ized absolute, 

1004-1005 
followingto terminal point, 

335-336 
matching, 924, 949-950 
patterns 

printing lines matching, 

224-226 
searching database fi lesfor, 

295 
pause, 817 

pausing execution, 813-814 

pbm, 1170-1171 

PBM images, displaying on 

4425 terminals, 357 
pbmclean, 348 
pbmfilters, 348-352 
pbmlife, 352-353 
pbmmake, 353 
pbmmask, 353-354 
PBM Plus package, programs, 

348-352 
pbmpscale, 354 
pbmreduce, 355 
pbmtext, 355-356 
pbmtolOx, 356 
pbmto4425, 357 
pbmtoascii, 357 
pbmtoatk, 358 
pbmtobg, 358 
pbmtocmuwm, 358-359 
pbmtoepsi, 359 
pbmtoepson, 359 
pbmtog3, 360 
pbmtogem, 360 
pbmtogo, 360-361 
pbmtoicon, 361 
pbmtolj, 361-362 
pbmtoln03, 362 
pbmtolps, 362 
pbmtomacp, 363 
pbmtomgr, 363 
pbmtopgm, 364 
pbmtopi3, 364 
pbmtopk, 364-365 
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pbmtoplot, 365-366 
pbmtoptx, 366 
pbmtoxlObm, 366 
pbmtoxbm, 367 
pbmtoybm, 367 
pbmtozinc, 367-368 
pbmupc, 368 
pclose( ), 991-992 
pcnfsd, 1355-1357 

authentication, 1355-1356 

file, 1357 

printing, 1356 

reconfiguration, 1357 
PCX files, converting to 

portable pixmaps, 368-369 
pcxtoppm, 368-369 
peers, getting names, 765 
permissions 

file 

changing, 748-749 
setting, 272-273 
port input/output, setting, 
788 

perror, 990-991 
personalità 817-818 
pfbtops, 369 
pgm, 1171-1172 
pgmbentley, 369 
pgmcrater, 370-371 
pgmedge, 371 
pgmenhance, 371-372 
pgmhist, 372 
pgmkernel, 372-373 
pgmnoise, 373 
pgmnorm, 373-374 
pgmoil, 374 
pgmramp, 374-375 
pgmtexture, 375-376 
pgmtofs, 376 
pgmtolispm, 376-377 
pgmtopbm, 377 
pgmtoppm, 378 
Photo-C D files, converting to 
portable pixmaps, 260-261 
phys, 818 

physical addresses, accessing, 
818 



pi3topbm, 379 

pie, versus gpic, 212-215 

commands, 212-213 
expressions, 213-214 
mode 212 
picttoppm, 379-380 

bugs, 379 

fontdir fileformat, 380 
ping, 1358 
pipe, 818-819 
pipdines(|), bash, 12 
pipes, creating, 818-819 
pjtoppm, 381 
pktopbm, 381 
PLIP devices, tuning 

parameters, 1357 
plipeonfìg, 1357 
pnm, 1173 
pnmalias, 381-382 
pnmarith, 382-383 
pnmeat, 383 
pnmcomp, 383-384 
pnmconvol, 384 
pnmerop, 385 
pnmcut, 385 
pnmdepth, 385-386 
pnmenlarge, 386 
pnmfile, 386-387 
pnmflip, 387 
pnmgamma, 387 
pnmhistmap, 388 
pnmindex, 388-389 
pnminvert, 389 
pnmmargin, 389-390 
pnmnlfilt, 390-391 

alpha-trimmed mean filter, 
390 

bugs, 391 

combining modes, 391 
edgeenhancement, 391 
opti mal estimation 
smoothing, 390 

pnmnoraw, 391-392 

pnmpad, 392 

pnmpaste, 392-393 

pnmrotate, 393 



pnmscale, 393-394 
pnmshear, 394-395 
pnmsmooth, 395 
pnmtile, 395 
pnmtoddif, 396 
pnmtofits, 396-397 
pnmtoiff, 399-400 
pnmtops, 397 
pnmtorast, 398 
pnmtosgi, 398-399 
pnmtosir, 399 
pnmtoxwd, 400 
popd (shell command), 39-40 
popenf ) function, 991-992 
popup-menu( ) action 

(xterm), 713 
port, 1091-1092 
portable anymaps 
antialiasing, 381-382 
bordering, 389-392 
changing maxval, 385-386 
compositing, 383-384 
concatenating, 383 
converting 

to D D I F format, 396 
to F IT S format, 396-397 
to PostScript, 397 
to red/blue3D glasse?, 

400-401 
toSGI imagefìle, 

398-399 
to Soli taire format, 399 
toSun raster files, 398 
toTIFF files, 399,400 
toXll window dumps 
400 

convolving, 384 

creating index of, 388, 389 

cropping, 385 

cutting rectanglesfrom, 385 
describing, 386, 387 
drawing histogramsfrom, 

388 
enlarging, 386 
fileformat, 1173 
flipping, 387 
gamma correction, 387 
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inverting, 389 

pasting rectangles into, 392, 
393 

performing arithmetic on, 

382, 383 
plain format, 391, 392 
programs 

constants 970 

format promotion, 972 

fu n cti on s su pporti n g, 970, 
971,972 

initialization, 971 

memory management, 971 

readingfiles 971 

types, 970 

writingfiles, 971, 972 
XEL mani pul ations, 
971-972 
replicating into specified 

size, 395 
rotating, 393 
scaling, 393, 394 
shearing, 394, 395 
smoothing, 395 
portatile bitmaps 

applying Rulesof Lifeto, 

352, 353 
converti ng 

to Andrew Tool kit raster 

objects 358 
toASCII graphics» 357 
to Atari DegasPI3 files, 
364 

to Bennet Yee"face" files, 
367 

to BitG raph graphics, 358 
to CM U window manager 

bitmaps 358-359 
to compresseci G raphO n 

graphics 360-361 
toDEC LN 03+ Sixel 

output, 362 
to encapsulated PostScript- 

style bitmaps 359 
to Epson printer graphics, 

359 



toGEM IMG files 360 
to Gemini lOx graphics 
356 

to Group 3 fax files 360 
toHP LaserJet format, 

361-362 
toM acP ai nt files 363 
toMGRbitmap, 363 
to packed format fonts, 

364- 365 

to portablegraymaps 364 
to PostScript, 362 
to Printronix printer 

graphics 366 
to Sun icons 361 
toUNIX plot files 

365- 366 

toXIO bitmaps 366 
toXll bitmaps 367 
toZinc bitmaps 367-368 

creating with specified size, 
353 

enlarging, 354 

fileformat, 1170-1171 

flipping pixelsin, 348 

programs 
constants, 968 
endian i/o, 967 
errors, 967 

fi le management, 967 
functions supporti ng, 

966-969 
initialization, 968 
keyword match ing, 967 
memory management, 968 
messages 967 
reading files 968 
types 968 

writingfiles 968-969 
reducing, 355 
portatile graymaps 

Bentleyizing, 369 
calculating textural features 

on, 375-376 
combiningth ree into a 

portable pixmap, 457-458 



converting 

to L isp machine format, 

376-377 
to portable bitmaps 377 
to portable pixmaps 378 
toUsenix FaceSaver 
format, 376 
creating from whitenoise, 
373 

enhancing edges, 371-372 
fileformat, 1171-1172 
mimicking cratered terrain, 

370-371 
normalizing contrast, 

373-374 
outlining edges, 371 
performing oil transfers on, 

374 

printing histogram of values, 

372 
programs 
constants, 969 
fu n cti ons su pporti ng, 

969-970 
initialization, 969 
memory management, 969 
reading files 970 
types 969 
writingfiles 970 
portable pixmaps 

blending together, 408-409 
brightening, 404 
changing pixel color, 

401-402 
changing saturation and 

value, 401 
converting 

toAbekasYUV files, 428 
to Atari DegasPll files, 
422 

to AutoCAD, 414-416 
to BMP files, 416 
to D EC sixel format, 

425-426 
toGIF files 416-417 
toHP PaintJet files 423 
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toH P PaintJet XL PCL 

fi lei 424 
tolLBM file, 418-419 
to Macintosh PICT file, 

422-423 
toM itsubishi S340-10 

fi lei 420-421 
toM otifUIL icon files, 

427 

toNCSA I C R format, 

417-418 
to PCX file, 421 
to portable graymaps, 

421-422 
tothreeportable graymaps, 

425 

tothreeraw YUV file, 

428-429 
to TrueVision Targa file, 

426 

toXll pixmaps, 427-428 

toXll puzzle fi les 
424-425 
creating, 408 

patterns, 410-411 

speci f yi n g color, 408 
creating from three portable 

graymaps, 457-458 
dimming 

toblack, 402 

everyother row, 409-410 
displacing pixels, 414 
dithering, 403 
extracting color from, 

419-420 
fi le format, 1173-1174 
files 

reading, 974 

writing, 974 
fractal forgeries, 404-407 
grayscaleassignments 

(performing), 402-403 
histograms (printing), 408 
Laplacian relief filters 

(running on), 413 
normalizing contrast, 409 



programs, functions 

supporting, 973-974 
quantizing colors, 411 
8-planequantization, 

412-413 
multi pi e fi I es, 412 
shifting lines, 413-414 
portmap, 1358-1359 
ports 

input/output functions, 816 
input/output permissions, 

setting, 788 
serial 

confi gu ring, 1394-1395 
parameters, 1392-1394 
setti ng/getting inforni a- 
tion, 1391-1395 
system, 1091-1092 
positional parameters 
bash, 14 
parsi ng, 38 
renaming, 42 
POSIX 

gawk compatibility, 171 
regex functions, 1005-1007 
compiling, 1005-1006 
errar reporti ng, 1006 
matching, 1006 
pattern buffer freeing, 
1007 

signal set operations, 
1019-1020 
PostScript 

bounding box, extracting, 
433 

files, convertingto portable 

anymaps, 434-435 
fonts 

tran slati ng from PFB 

format to ASCII, 369 
translati ngfromPFB 
format to ASCII, 369 
imagedata, converti ng into 
portable graymap, 
433-434 
pound sign (#) 
bash comments, 14 
bash special parameters, 15 



pow( ) function, 918 
powerd, 1359-1360 
powers (raisìng numbers to), 
918 

PPID variable(bash), 15 
ppm, 1173-1174 
ppm3d, 400-401 
ppmbrighten, 401 
ppmchange, 401-402 
ppmdim, 402 
ppmdist, 402-403 
ppmdither, 403 
ppmflash, 404 
ppmforge, 404-407 

bugs, 407 

options, 405-407 
ppmhist, 408 
ppmmake, 408 
ppmmix, 408-409 
ppmnorm, 409 
ppmntsc, 409-410 
ppmpat, 410-411 
ppmquant, 411-412 
ppmquantall, 412 
ppmqvga, 412-413 
ppmrelief, 413 
ppmshift, 413-414 
ppmspread, 414 
ppmtoacad, 414-416 
ppmtobmp, 416 
ppmtogif, 416-417 
ppmtoicr, 417-418 
ppmtoilbm, 418-419 
ppmtomap, 419-420 
ppmtomitsu, 420-421 
ppmtopcx, 421 
ppmtopgm, 421-422 
ppmtopil, 422 
ppmtopict, 422-423 
ppmtopj, 423 
ppmtopjxl, 424 
ppmtopuzz, 424-425 
ppmtorgb3, 425 
ppmtosixel, 425-426 
ppmtotga, 426 
ppmtouil, 427 
ppmtoxpm, 427-428 
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ppmtoyuv, 428 
ppmtoyuvsplit, 428-429 
PPP 

daemon, 1360-1369 

statisti cs, printing, 
1369-1370 
pppd, 1360-1369 

authentication, 1366-1367 

diagnostics, 1368 

examples, 1367-1368 

files, 1366-1369 

options, 1360-1366 

routing, 1367 

signals, 1369 
pppstats, 1369-1370 
pr, 429-430 
preprocessor, 81-84 
preprocessors, imake, 264-267 
printf function, 992-996 

bugs, 995-996 
printf statement, awk, 

167-168 
printing 

aliases, 35 

application resources, 5 
banners, 1210 
converti ng text files for, 

429-430 
files, in reverse, 503-504 
histogramsof portable 

pixmaps, 408 
hostlD s,258-259 
lines matching a pattern, 

224-226 
log messages (RCS files), 

458-460 
machine architectu re, 8 
offline, 299-301 
packet mute, 1409-1412 
pcnfsd, 1356 
PPP statistica 1369-1370 
printer/plotter accounting 

files (reading), 1354-1355 
removingjobsfrom queue, 

301-302 
ripple test pattern, 302 
signal messages, 996 



spool queue examination, 

298-299 
system activity summary, 

573 

system error messages, 

990- 991 
timezones, 1419 
user/ system times, 43 
seealso line printer 

priority values, getting range, 

830-831 
privileges 

I/O , changing level, 

788-789 
setuid (RCS files), 67-68 
/proc, 1174-1180, 1236 
bugs, 1180 

hierarchy outline, 1174- 
1180 

proc filesystem, 1125 
proc_sel, 1430-1431 
process control, initialization, 

1307-1309, 1397-1399 
process groups, sending 

signals to, 790-791, 960 
process substitution (bash), 

20 
processes 

0, making idle, 774 
accounting, switching on/ 

off, 742 
child, creating, 751, 758 
closing, pclosef ) function, 

991- 992 

displaying tree of, 435-436 
execution, suspending, 1061 
execution domain, setting, 

817-818 
group identity, setting, 845 
group I D s 

getti ng/settìng, 845-846 
real and effective(s9tting), 
846-847 
groups 

access I i sts (getti ng/setti ng), 

761-762 
IDs(getting), 761 



identifying, 154-155 

IDs, getting, 766 

listi ng most CPU -intensive, 

533-535 
opening, popenf ) function, 

991-992 
parents, IDs (getting), 766 
priorities, altering, 

1375-1376 
priority, changing, 814 
reporti ng status, 430-433 
SCH ED_RR interval, 

getting, 831 
scheduling priorities, 

getting/setting, 766-767 
selecting, by criteria, 

1430-1431 
sending signals to, 790 
raise function, 1000 
starti ng, on consoles, 1066 
terminating, 283-284, 

739-740 
by name. 284 
times, getting, 878-879 
tracing, 820 
user I D s 
getting, 773 

real and effecti ve (setti ng), 

847-848 
setting, 848-849 
waitingfor terminati on, 

886-889 
yielding processor, 835 
processor, time used (deter- 

mining), 905 
profil, 819 
profiling, 819 
programs 

executing, 754-755 
portable anymap 
constants, 970 
format promotion, 972 
fu n cti ons su pporti n g, 

970-972 
initialization, 971 
memory management, 971 
readingfiles 971 
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types, 970 

writingfiles, 971-972 
XEL mani pulations, 
971-972 
portable bitmap, functions 

supporting, 966-969 
portable graymap 
constante 969 
functions supporting, 

969-970 
initialization, 969 
memory management, 969 
readingfiles, 970 
types, 969 
writingfiles, 970 
recompiling, make utility, 

310-312 
running, in new session, 

1395 
terminating 

abort( ) function, 892 
assert( (function, 

895-896 
exit) ) function, 917 
promoting directories, 39-40 
prompt (ftp command), 151 
PROM PT COM MAND 

variable (bash), 17 
prompting (bash), 26 
properties, consoles, 1067 
protocols 

protocols definition file, 

1180-1181 
RPC, rpcgen compiler, 

464-466 
Telnet, interface, 507-512 
XIE, testing, 645-654 
proxy ftp (ftp command), 151 
proxy servers, LBX, 286-287 
PRT ray tracers, converting 
output to portable pixmaps, 
333 

prunehistory, 1370-1371 
ps, 430-433 

bugs, 433 

field descriptions, 432 
options, 430-431 



sort keys, 431-432 

updating, 432, 436 
PS1 variable (bash), 16 
PS2 variable (bash), 16 
PS3 variable (bash), 17 
PS4 variable (bash), 17 
psbb, 433 

pseudo-fi lesystems, /proc, 
1174-1180 
bugs, 1180 
hierarchy outline, 
1174-1180 
pseudo-random numbers, 

generating, 912-913 
psidtopgm, 433-434 
pstopnm, 434-435 
pstree, 435-436 
psupdate, 436 
ptrace, 820 

pushd (shell command), 40 
put (ftp command), 151 
put_file_last, 1431 
putc( ) function, 997-999 
putchar( ) function, 997-999 
putenv, 996-997 

errors, 996 
putpwent( ) function, 997 

errors, 997 
puts( ) function, 997-999 
pututline( ) function, 948 
putw function, 948 
pwd (ftp command), 151 
pwd (shell command), 40 
PWD variable (bash), 15 

Q 



qio, 998 

Q RT ray tracer, converting 
output to portable pixmaps, 
436-437 

qsort, 1000 

quantìzing colors (pixmaps), 
411 

8-plane quantization, 

412-413 
multiple fi les, 412 



question marks(?) 

bash special parameters, 15 

ftp command, 152 
queues, inserting/removing 

items, 957 
quit command 

ftp command, 151 

telnet, 508 

xauth, 591 
quit( ) action (xterm), 714 
quota, 437 

quotacheck, 1371-1372 

quotactl, 821-822 

quotaoff, 1372-1373 

quotaon, 1372-1373 

quotas 

disk, manipulating, 821-822 
remote mach ines, 1012 

quote (ftp command), 151 

quoting (bash), 14 

R 



Radix32 routine, 966 
raise function, 1000 
ram, 1094-1095 
rand( ) function, 1001 
random numbers, generating, 

1001-1002 
RANDOM variable (bash), 15 
random( ) function, 

1001-1002 
randomizing strings, 1032 
ranlib, 437-438 
rarp, 1373 

RARP table, manipulating, 
1373 

rasttopnm, 438 

raw grayscale bytes, convert- 
ing to portable graymaps, 
439 

raw RGB bytes, converting to 
portable pixmaps, 439-440 
rawtopgm, 439 
rawtoppm, 439-440 
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ray tracers 

converti ng output to 

portable pixmaps, 333 
Q RT , converti ng output to 
portable pixmaps, 436-437 
rcp, 440-441 
RCS (Revision Control 
System), 447-449 
automatic identification, 
449 

commands, 447-449 
directories, creating, 

447-449 
files 

changing attri butes, 

441-443 
cleanìng, 443-445 
comparing ra/isions, 

445- 446 
freezing configuration, 

446- 447 
functions, 447 

revisions, merging, 449-451 
rcs, 441-443 

bugs, 443 

compatibility, 443 

diagnostica, 443 

environment, 443 

files, 443 

options, 441-443 
RCS files 

controlling access, 67 

format, 1181-1183 

modes, 67 

organization (diagram), 
1182 

printing log messages, 

458-460 
retrieving revisions, 71-75 
specifying, 66-67 
stori ng revisions, 64-69 

setuid privi leges, 67-68 
temporary files, 67 
RCS keyword strings, 
identifying, 262-263 
RCSBIN environment 
variable, 105 



rcsclean, 443-445 
rcsdiff, 445-446 
rcsfile, 1181-1183 

organization (diagram), 
1182 
rcsfreeze, 446-447 
rcsintro, 447-449 

automatic identification, 
449 

RCS functions, 447 
rcsmerge, 449-451 
rdev, 1373-1375 
rdiff (cvscommand), 101 
rdist, 451-454 

bugs, 454 

diagnostics, 454 

files, 453 

options, 451-452 
re comp function, 1005 
re exec function, 1005 
read (shell command), 40 
read( ), fìledescriptors, 822 
readdir, 823 
readdi r( ) calls, setting 
position, 1015-1016 
readdir( ) function, 

1002-1003 
ReadlnD escriptor routine, 
966 

ReadlnFile routine, 966 
readline library, 27-32 

commands, 29-32 

controlling key bindings, 27 

customizing, 27 

denoti ng keystrokes, 27 

macro definitions, 28 

parser di recti ves, 28-29 
$ds9, 29 
$endif, 29 
$if, 28-29 

variables, 28 
bdl-style 28 
comment-begin, 28 
completi on-query-items, 
28 

convert-meta, 28 
editing-mode 28 
expand-tìlde, 28 



horizontal-scroll-mode 28 
keymap, 28 

mark-modified-lines, 28 

meta- fi ag, 28 

output-meta, 28 

show-all-if-ambiguous. 28 
readlink, 823-824 
readonly (shell command), 40 
readv, 824-825 
readv( ) function, 1003-1004 
realloc( ) function, 976-977 
realpath, 1004-1005 
reboot, 825-826 
recompiling programs, make 

utility, 310-312 
recompressing Z files, 

734-735 
reconfig, 454 
recv, 151, 826-828 
recvfrom, 826-828 
recvmsg, 826-828 
redirection, 21-23 

duplicatingfiledescriptors, 
23 

here-documents, 22-23 
input, 22 

openingfiledescriptors, 23 
operato rs, 21 
output, 22 
redraw( ) action (xterm), 714 
ref, 455-456 

elvis interaction, 455 
environment, 455 
files, 455 
options, 455 
search method, 455 
refreshing screen (X), 684-685 
refs files, generating, 87-88 
regcomp function, 1005-1007 
regerror function, 1005-1007 
reget (ftp command), 151 
regex functions, 1005 
POSIX, 1005-1007 
compiling, 1005-1006 
errar reporti ng, 1006 
matching, 1006 
pattern buffer freeing, 
1007 
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regexec function, 1005-1007 
regfreefunction, 1005-1007 
regular expressi ons 

grep, 225-226 

sed, 476-477 
release(cvscommand), 101 
remote execution server, 

1376- 1377 

remote file copying, 440-441 
remote logging, 1403 
remote login server, 

1377- 1378 

remote logins, 460-461 
Kerberos authentication, 
461 

remote machines, starting X 

programson, 676 
remote quota server, 1384 
remote shell, 466-467 
remote shell server, 

1385-1386 
Remote Start client, see rstart 
Remote Start rsh nel per, see 

rstartd 

remote status, displaying, 472 
remote systems, command 

execution, 569-571 
remote user communication 

server, 1405-1406 
remotehelp (ftp command), 

151 

remotestatus (ftp command), 

151 
remove, 1008 

cvs command, 101-102 
xauth command, 591 
removefilefree, 1431-1432 
remque( ) function, 957 
renarne, 828-829 
renarne (ftp command), 151 
renice, 1375-1376 
REPLYvariable(bash), 15 
REPLYTO environment 

variable, 529 
repquota, 1376 
res_init, 1008-1011 



res_mkquery, 1008-1011 
res query, 1008-1011 
res search, 1008-1011 
res send, 1008-1011 
reserved words(bash), 12 
reset, 456, 539-542 

compatibility, 542 

options, 540 

setting environment, 540 

terminal typemapping, 
540-541 
reset (ftp command), 151 
resize, 456-457 
resolver, 1183-1184 
resolver routines, 1008-1011 
resolving hostnames, 

1238-1239 
resource editor, see editres 
resources 

limits, getti ng/setting, 
767-768 

usage, getting, 767-768 
restart (ftp command), 151 
return (shell command), 40 
return value, errors, 797 
rev, 457 

reverse line feeds, filtering, 76 
Revision Control System, see 
RCS 

rewind function, 927-928 
rewinddir( ) function, 1011 
rexecd, 1376-1377 
bugs, 1377 
diagnostics, 1377 
protocol, 1376-1377 
RGB colorname databases, 

uncompiling, 488 
rgb3toppm, 457-458 
rindex( ) function, 953 
rint( ) function, 1011-1012 
ripple test pattern (printing), 

302 
rlog, 458-460 
rlogin, 460-461 
rlogind, 1377-1378 
rm, 461-462 



rmdir, 462, 829-830 

bugs, 830 

errors, 829 

options, 462 
rmdir (ftp command), 152 
rmmod, 462-463 
rnews, 463-464 
Rock Ridgefilesystem, 1125 
root logins, tty lines(listing), 

1184 
root di recto ri es 

changing, 750-751, 1273 
root filesystem, mounting, 
849 

root window (X), setting 
parameters, 693-694 

round-robin scheduling, 834 

rounding integers, 904 

rounding numbers, 
1011-1012 

route, 1379-1380 

routed, 1380-1382 
bugs, 1382 
files, 1382 

gateways, 1381-1382 
options, 1381 
request packets, 1381 
response packets, 1381 
starting, 1380 
routines 

ICCcancel, 956 
ICCclose, 956 
ICCcommand, 956 
ICCgo, 956 
ICCopen, 956 
ICC pause, 956 
I C C reserve, 956 
ICCsettimeout, 956 
libinn library, 962-966 

CAclose, 964 

CAlìstopen, 964 

CAopen, 964 

ClossOnExec, 965 

DD check, 965 

DDend, 965 

DD start, 965 

GetConfigValue, 965 
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GetFileConfigValue, 965 
GetFQDN, 965 
GetM oderatorAddress, 
965 

GetResourceU sage, 965 
GetTimelnfo, 965 
HeaderFind, 964 
I N N Version, 966 
LockFìle, 965 
NNTPcheckartide 965 
NNTPconnect, 965 
NNTPIocalopen, 965 
N NTPremoteopen, 965 
N NTPsendarticle, 966 
N NTPsendpassword, 966 
Radìx32, 966 
RsadlnD earriptor, 966 
ReadlnFile 966 
SdtN onBlocking, 965 
libpbm, 966-969 
constants, 968 
endian i/o, 967 
errors, 967 

fi le management, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 
readingfiles, 968 
types, 968 

writingfiles, 968-969 
libpgm, 969-970 

constants, 969 

initialization, 969 

memory management, 969 

readingfiles, 970 

types, 969 

writingfiles, 970 
libpnm, 970-972 

constants, 970 

format promotion, 972 

initialization, 971 

memory management, 971 

readingfiles, 971 

types, 970 

writingfiles, 971-972 
XEL mani pulation, 972 
XEL mani pulations, 971 



routing, pppd, 1367 
RPC 

program numbers, 
convertingto DARPA port 
numbers, 1358-1359 

protocol compiler, seerpcgen 

services, reporti ng informa- 
tion, 1383-1384 
rpc.rquotad, 1384 
rpc.rusersd, 1382-1383 
rpc.rwalld, 1383 
rpcgen, 464-466 

options, 465-466 

preprocessor symbols, 465 
rpcinfo, 1383-1384 
rquota( ) protocol, 1012 
rquotad, 1384 
rsh, 466-467 
rshd, 1385-1386 
rstart, 467-468 
rstartd, 468-471 

configuring, 469 
keywords, 470 

installi ng, 469 

options, 469 
rtag (cvs command), 102 
runique(ftp command), 152 
rup, 472 
rusers, 472-473 
mail, 473 
rwho, 474 
rwhod, 1386-1387 

S 



saving stack context, 1018 
/sbin directory, 1237 
sbrk, 746 

scandir! ) function, 

1012-1013 
scanf functions, 1013-1015 

bugs, 1015 

conversions, 1014-1015 
flags, 1014 
return values, 1015 
sched get priority max, 
830~831~ 



sched get priority min, 

830-831" 
sched getparam, 832 
sched getscheduler, 833-835 

errors, 834 
policies, 833 

SCHED_FIFO, 833-834 
SCH ED_OTH ER, 834 
SCH ED_RR, 834 
responsetime, 834 
schedrrgetinterval, 831 
sched setparam, 832 
sched setscheduler, 833-835 
errors, 834 
policies, 833 

SCH ED_FIFO, 833-834 
SCH ED_OTH ER, 834 
SCH ED_RR, 834 
responsetime, 834 
schedyield, 835 
scheduling 

algorithm, getti ng/setting, 

833-835 
parameters, getting/setting, 

832 
policies, 833 
first in - first out, 

833-834 
round- robin, 834 
ti me-shari ng, 834 
priorities 

getting/setting, 766-767 
valueranges, 830-831 
yielding processor, 835 
screen, clearing, 70-71 
screen savers, beforelight, 

47-48 
script, 474-475 
scripts, chat, 1270 
scroll-back( ) action (xterm), 
714 

scroi l-forw( ) action (xterm), 

714 
SCSI drivers 

disk drives, 1095-1096 
tapedevices, 1096-1100 
sd, 1095-1096 



servers 



1477 



searching 

binary trees, 1056 

strings, for character sets, 
1035-1039 
second extended filesystems 

creating, 1324-1325 

lost+found directory, 1327 

tunableparameters 
(adjusting), 1412-1413 
SECONDSvariable(bash), 15 
secure( ) action (xterm), 713 
securetty, 1184 
security 

sysklogd, 1403-1404 

X server, 688-689 

xterm, 712 
sed, 475-480 

addresses, 476 

bugs, 480 

commands, 478-479 

grouping, 478 

syntax, 476 
comments, 477 
diagnostica, 479-480 
options, 475 

regular expressions, 476-477 
replacement pattern 

symbols, 477 
search pattern symbols, 
476-477 
seed48( ) functions, 912 
seekdir( ) function, 

1015-1016 
select, 835-837 
select-cursor-end action 

(xterm), 714 
select-cursor-start( ) action 

(xterm), 714 
sdect-end( ) action (xterm), 
714 

sdect-extend( ) action 

(xterm), 714 
sdect-start( ) action (xterm), 

714 

selections, copying into cut 
buffers, 598-599 



semaphore sets 

control operations, 837-839 
GETALL, 838 
GETNCNT, 838 
GETPID, 838 
GETVAL, 838 
GETZCNT, 838 
I PC_RM I D , 838 
IPC_SET, 838 
IPC_STAT, 837 
SETALL, 838 
SETVAL, 838 
identifiers (getting), 

839-840 
operations, 840-842 
semctl, 837-839 
errors, 838-839 
operations, 837-838 
GETALL, 838 
GETNCNT, 838 
GETPID, 838 
GETVAL, 838 
GETZCNT, 838 
I PC_RM I D , 838 
IPC_SET, 838 
IPC_STAT, 837 
SETALL, 838 
SETVAL, 838 
semget, 839-840 
semop, 840-842 
send, 842-843 

ftp command, 152 
send arguments command 

(telnet), 508-509 
send-signal( ) action (xterm), 
714 

sendmail, 1387-1390 

aliases, 1390 

exit status codes, 1390 

files, 1390 

flags, 1388 

options, 1389-1390 
sendmsg, 842-843 
sendport (ftp command), 152 
sendto, 842-843 
serial lines 

monitoring, 1359-1360 

network interfaces, 
attaching, 1399-1401 



serial mouse interface, 
1092-1094 

M icrosoft protocol, 1093 
MM protocol, 1094 
M ouseSystems protocol, 

1093 
Sun protocol, 1093 
serial ports 

configuring, 1394-1395 
parameters, 1392-1394 
setting/ getting information, 
1391-1395 
serial terminal lines, 1101 
servers 

biff, 1274-1275 
controlling with xdm, 

612-613 
DARPA FTP, 1301-1304 
requestssupported, 
1302-1303 
DARPA Telnet protocol, 

1406-1407 
DARPA TFTP, 1407 
domain 

lookingup hostnames 

with, 257-258 
resolver routi nes, 
1008-1011 
font(X) 

di splayi ng information 

about, 145 
generating BD F fonts 

146-147 
lìstìng fonts 145-146 
interned atoms, listing, 

668-669 
Internet, xinetd (starting 

with), 655-664 
Internet domain nameserver, 
1334-1338 
boot file 1334-1336 
control interface, 

1338-1339 
master file, 1336 
queryìng, 1350-1353 
signals 1337 
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SOA record, 1336-1337 
stoppi ng/restartìng, 1338 
synchronizing database, 
1338 

I nternet superserver, 

1305-1307 
LBX proxy server, 286-287 
logged-in users, 1382-1383 
news, sending U senet 

articlesto, 267-269 
NFS 

autenticati on/print 
request, 1355-1357 
mount information, 1396 
NNTP, 1347-1349 

getti ng li stsfrom, 206-207 
passwords 1170 
retrieving U senet arti ci es 
from, 340-341 
portmap, 1358-1359 
remote execution, 

1376-1377 
remote login, 1377-1378 
remote quota, 1384 
remote shell, 1385-1386 
remote user communication, 

1405-1406 
specifying, xdm, 607-608 
system status, 1386-1387 
message format, 
1386-1387 
X W indow System 
access control program, 

643-645 
display server, 685-690 
fileutility, 587-592 
font server, 641-643 
information utility, 614 
killing clients 666-667 
starti ng, 664-666 
virtual framebuffer, 
717-718 

Xll 

performance compari son 
program, 585-586 

performance test program, 
577-585 



XF86_8514, 615 
XF86_Accel, 614-623 

configuration, 615-616 

file» 622 

options, 616 

setup, 616-622 
XF86_AGX, 615 
XF86_Mach32,615 
XF86_Mach64, 615 
XF86_Mach8, 615 
XF86_Mono, 624-627 

configuration, 624 

file, 626 

setup, 624-626 
XF86_P9000, 615 
XF86_S3, 615 
XF86_ SVGA, 627-631 

configuration, 627-628 

fi lei 630-631 

options» 628 

setup, 628-630 
XF86_VGA16, 631-633 

configuration, 631 

files, 633 

options, 632 

setup, 632 
XF86_W32,615 
XFree86, 636-641 

configuration, 636 

environment variables. 
637 

files, 638-639 

key combinations 638 

network connections, 
636-637 

options, 637-638 

setup, 638 
services, 1184-1186 
bugs, 1186 
files, 1186 

Internet, listing, 1184-1186 
N FS, daemon, 1347 
RPC, reporting information, 
1383-1384 
Session M anager Proxy, see 
sm proxy 



sessions 

creati ng, setsid, 848 
IDs, getting, 768 
typescripts, creating, 

474-475 
X Session M anager, 694-698 
default startup appi i ra- 
ti ons 695 
options 695-698 
proxy, 698 

remote applicati ons 698 
Session menu, 695-696 
SM_SAVE_DIR 
environment variable. 
695 
starti ng, 695 
tester, 698-699 
.xsession file, 695 
xdm, 600 
sessreg, 480-481 
set 

shell command, 40-42 
telnet command, 509-510 
set-allowl32( ) action (xterm), 
715 

set-altscreen( ) action (xterm), 
715 

set-appcursor( ) action 

(xterm), 715 
set-appkeypad( ) action 

(xterm), 715 
set-autolinefeed( ) action 

(xterm), 715 
set-autowrap( ) action 

(xterm), 715 
set-cursesemul( ) action 

(xterm), 715 
set-jumpscroll( ) action 

(xterm), 715 
set-marginbell( ) action 

(xterm), 715 
set- reverse- vi deo( ) action 

(xterm), 715 
set-reversewrap( ) action 

(xterm), 715 
set-scroll-on-key( ) action 

(xterm), 715 
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set-scroll-on-tty-output( ) 

action (xterm), 715 
set-scrollbar( ) action (xterm), 

715 

set-tek-text( ) action (xterm), 
715 

set-terminal-type( ) action 

(xterm), 715 
set-visibility( ) action (xterm), 

715 

set-visual-bell( ) action 

(xterm), 715 
set-vt-font( ) action (xterm), 

714 

setbuf function, 1016-1017 
setbufferfunction, 1016-1017 
setdomainname, 760 
setegid, 846-847 
setenv( ) function, 1017 
seteuid, 847-848 
setfdprm, 1391 
setfsgid, 843-844 
setfsuid, 844 
setgid, 845 

setgrentf ) function, 932-933 
setgroups, 761-762 
sethostid, 762-763 
sethostname, 763 
setitimer, 763-764 
bugs, 764 

defining values, 764 
errors, 764 
return value, 764 
timertypes, 764 
setjmp( ) function, 1018 
setlinebuf function, 

1016-1017 
setlocalef ) function, 

1018-1019 
setmntent( ) function, 

935-936 
SetNonBlocking routine, 965 
setpgid, 845-846 
setpgrp, 845-846 
setpriority, 766-767 
setprotoent( ) function, 
941-942 



setpwent( ) function, 943 
setregid, 846-847 
setreuid, 847-848 
setrlimit, 767-768 
setserial, 1391-1395 

configuration consider- 
ations, 1394-1395 

files, 1395 

options, 1392 

parameters, 1392-1394 
setserventf ) function, 946 
setsid, 848, 1395 

errors, 848 
setsockopt, 769-772 

bugs, 772 

errors, 771 

options recognized, 770-771 
S0_BR0ADCAST, 771 
S0_DEBUG, 770 
S0_D0NTR0UTE, 770 
S0_ERR0R, 771 
SO KEEPALIVE, 770 
S0_LIN GER, 770 
SO_RCVBUF, 771 
S0_RCVL0WAT, 771 
S0_RCVTIM EO, 771 
S0_REU SEAD D R, 770 
SO_SNDBUF, 771 
S0_SNDL0WAT, 771 
S0_SNDTIME0, 771 
SO_TYPE, 771 
return value, 771 

setstate( ) function, 
1001-1002 

setterm, 482-483 

setti meof day, 772-773 

setuid, 848-849 

setup, 849 

setusershell( ) function, 

946-947 
setutent( ) function, 947 
setvbuf function, 1016-1017 
SGI image files, convertingto 

portable anymaps, 483-484 
sgitopnm, 483-484 
sh, expansion, 19 



shadow directories (creating), 

294 
shar, 484-487 

files, unpacking, 560-561 

options, 484-486 
shared libraries, selecting, 883 
shared memory 

al locati ng, 851-853 
controlling, 849-851 
commands. 850 
system cai Ig, 851 
operations, 853-854 
shell variables(bash), 15-18 
allow-null_glob_expansion, 
17 

auto_resume, 18 
BASH , 15 

BASH_VERSION, 15 
cdable_vars, 18 
CDPATH, 16 
command_oriented_history, 

17 
ENV, 16 
EUID, 15 
FCEDIT, 17 
FIGNORE, 17 
glob_dot_filenames, 17 
histchars, 17-18 
HISTCMD,16 
H I ST FILE, 17 
HISTFILESIZE, 17 
history control, 17 
HISTSIZE, 17 
HOM E, 16 

hostname_completion_file, 
18 

HOSTTYPE, 16 
IFS, 16 

IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 

MAIL_WARNING, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_exit_on_failed_exec, 18 
noclobber, 18 
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nolinks, 18 
notify, 17 
OLDPWD, 15 
OPTARG, 16 
OPTERR, 17 
OPTIND, 16 
OSTYPE, 16 
PATH, 16 
PPID, 15 

PROM PT_COM M AND, 

17 
PS1, 16 
PS2, 16 
PS3, 17 
PS4, 17 
PWD, 15 
RANDOM , 15 
REPLY, 15 
SECONDS, 15 
SH LVL,15 
TMOUT.17 
UID, 15 
shell s 

archi ives, creati ng, 484-487 
Bourne-again, 11-46 

alias, 23-24 

arguments, 11 

arithmetic evaluation, 34 

blanks, 12 

bugs 46 

command execution, 25 
comments 14 
compound commands 13 
control operators 12 
environments 25-26 
erape character, 14 
exit status 26 
expansion, 18-21 
file* 46 
functions 23 
history list, 32-33 
invocation, 45-46 
job control, 24-25 
liis 12-13 
meta characters 12 
names, 12 
options 11 



parameters, 14-15 
pi pel i nes ( |), 12 
prompting, 26 
quoti ng, 14 
readline, 27-32 
redirection, 21-23 
reserved words 12 
shell vari ables 15-18 
signals 25 

si mpl e commands 12 
words 12 
built-in commands, 35-45 
alias 35 
bg, 35 
bind, 35 
break, 35 
builtin, 35 
ed, 35-36 
command, 36 
continue, 36 
dedare, 36 
dirs 36 
echo, 36-37 
enabli ng/disabli ng, 37 
a/al, 37 
exec, 37 
exit, 37 
export, 37 
fc, 37-38 
fg, 38 
getopts 38 
hash, 38 
help, 38 
history, 39 
jobs 39 
kill,39 
let, 39 
locai, 39 
logout, 39 
popd, 39-40 
pushd, 40 
pwd, 40 
read, 40 
readonly, 40 
return, 40 
set, 40-42 
shift, 42 



susoend, 42-43 

test expr, 43 

times, 43 

trap, 43-44 

type, 44 

ulimit, 44-45 

umask, 45 

unalias 45 

unset, 45 

wait, 45 
commands, executing, 1047 
exiting, 37 
interactive, 45 
login, 45 

changing, 63 

exiting, 39 

pathnames 1186 
remote, 466-467 

server, 1385-1386 
suspending execution, 42-43 
user, getting, 946-947 
shellsfile, 1186 
shift (shell command), 42 
shlock, 487 

SH LVL variatile (bash), 15 
shmctl, 849-851 

commands, 850 

errors, 851 

system calls, 851 
shmget, 851-853 

bugs, 853 

errors, 852 

system calls 852 
shmop, 853-854 
show-all-if-ambiguous 
vari abl e (readline), 28 
showmount, 1396 
showrgb, 488 
shrinkfile, 488 
shutdown, 855, 1396-1397 

bugs, 1397 

errors, 855 

files, 1397 

options, 1397 
sigaction, 855-857 
sigaddset, 1019-1020 
sigblock, 858 
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sigdelset, 1019-1020 
sigemptyset, 1019-1020 
sigfillset, 1019-1020 
siggetmask, 858 
siginterruptf ) function, 1019 
sigismember, 1019-1020 
sigmask, 858 

signal, 857-858, 1248-1249 

bugs, 1249 

signal messages, printing, 
996 
signals 

available (list of), 1248-1249 
bash, 25 
block ed 

changing list of, 856 
releasing, 858-859 
changing process action, 

855-856 
describing with strings, 1038 
handling, 857-858 
interrupting system cai I s, 

1019 
masks 

manipulating, 858 
replacing, 856 
pending, examining, 856 
POSIX signal set operations, 

1019-1020 
sending to processes, raise 

function, 1000 
waitingfor, 817 
signature^ tin, 528 
sigpause, 858-859 
sigpending, 855-857 
sigprocmask, 855-857 
sigreturn, 859 
sigsetmask, 858 
sigsuspend, 855-857 
sigvec, 860 

simplecommands(bash), 12 
simpleinit, 1397-1399 

bugs, 1399 

files, 1398 
sin( ) function, 1020-1021 
sinh( ) function, 1021 
sirtopnm, 488-489 



site (ftp command), 152 
size, 489-490 

copying, 489-490 
ftp command, 152 
options, 489 
slattach, 1399 
sic command (telnet), 510 
sldtoppm, 490-491 
sleep( ) function, 1021 
sliplogin, 1399-1401 
diagnostics, 1400 
/etc/slip.hosts format, 1400 
example, 1400 
parameters, 1400 
smb filesystem, 1126 
smproxy, 491-492 
snprintf function, 992-996 
SOCK DGRAM sockets, 

860-861 
SOCK RAW sockets, 861 
SOCK RDM sockets, 861 
SOCK'SEQPACKET sockets, 

860-861 
SOCK STREAM sockets, 

860-861 
socket, 860-861 
errors, 861 
socket types, 860 
SOCK_DGRAM, 

860-861 
S0CK_RAW, 861 
SOCK_RDM,861 
SOCK_SEQPACKET, 

860-861 
SOCK_STREAM, 
860-861 
socketcall, 862 
socketpair, 862-863 
sockets 
connections 

accepti ng, 740-741 
initiating, 752-753 
I i sten i n g for, 792-793 
creating, 860-861 
names 

binding, 745-746 
getti ng, 769 



options, 770-771 

getti ng/setti ng, 769-772 
S0_BR0ADCAST, 771 
SO_DEBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO_KEEPALIVE, 770 
SO_LIN GER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIM EO, 771 
SO_REU SEAD D R, 770 
SO_SNDBUF, 771 
SO_SNDLOWAT, 771 
SO_SNDTIMEO, 771 
SO_TYPE, 771 
pairs, creating, 862-863 
peers, getting names, 765 
receiving messages from, 

826-828 
sending messages from, 

842-843 
system calls, 862 
types, 860 

SOCK_DGRAM, 

860-861 
SOCK_RAW, 861 
SOCK_RDM, 861 
SOCK_SEQPACKET, 

860-861 
SOCK_STREAM , 
860-861 
soft-reset( ) action (xterm), 
715 

Solitai re files, converting to 

portatile anymaps, 488-489 
sort, 492-493 
sorted arrays, searching, 

900-901 
sorted files, removing 

duplicate lines, 560 
sorted word lists, compress- 

ing/uncompressing, 496 
sorting arrays, 1000 
sound drivers, boot-time 

parameters, 1224 
source command (xauth), 591 
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spaces, converting to tabs, 559 
spctoppm, 494 
special parameters, bash, 
14-15 

! (exclamation points), 15 
#(pound signs), 15 
$ (dollar signs), 15 
* (asterisks), 15 
- (hyphens), 15 
? (question marks), 15 
@ (at signs), 15 
_ (underscores), 15 
0, 15 

spdl-checking, 274, 280 

buildhash, 279 

findaffix, 280 

icombine, 281 

ijoin, 281 

ispell, 274-279 

ispell dictionaries, 
1084-1090 
affix fi le, 1084-1085 
alternate stri ng characters, 
1087 

character-set section, 1086 
flags 1088 
headers. 1085 
optionsstatements, 

1085-1086 
prefix/suffixtables, 1088 
rootwords, 1084-1085 

munchlist, 279-280 

tryaffix, 281 
split, 494-495 

splittìngfiles, 85-86, 119-120 
spool queue 

examining, 298-299 
removingjobs from, 
301-302 
SPOT satellite images, 
converting to portable 
graymaps, 495 
spottopgm, 495 
sprintf function, 992-996 
sprintf( ) function, awk, 

167-168 
sputoppm, 495-496 



sq, 496 

sqrt( ) function, 1023 
square roots (returning), 1023 
srand( ) function, 1001 
srand48( ) functions, 912 
srandomf ) function, 

1001-1002 
sscanf function, 1013-1015 
st, 1096-1100 

ioctlf ) calls, 1097-1100 
return values, 1100 
stack, saving context, 1018 
standard colormap utility (X), 

699-700 
standard error output, 

redirecting, 22 
standard output, redirecting, 

22 

start-cursor-extend( ) action 

(xterm), 714 
start-extend( ) action (xterm), 

714 
startup time 

adjustingtoGMT, 1424- 

1425 
converting, 1430 
startx, 496-497 
stat, 863-864 
statements, awk, 167-168 
states (system), updating, 

1414-1415 
statfs, 865-866 
status 
cvs, 102 
ftp, 152 

telnet command, 512 
stdarg, 1023-1024 
stdio library, 1025-1027 

bugs, 1026 

functions, 1026-1027 
stime, 866 

stpcpy( ) function, 1027-1028 
strcasecmp( ), 1028 
strcat( ) function, 1028-1029 
strchr( ) function, 1029 
strcmp( ) function, 1029-1030 
strcollf ) function, 1030 
strcpy( ) function, 1030-1031 



strcspn( ) function, 

1038-1039 
strdup( ) function, 1031 
stream-oriented editor, see sed 
streams 

binary, input/output 
(getti ng), 926-927 
block buffered, 1016 
buffering operations, 

1016-1017 
checking/resetting status, 

919-920 
closing, 919 
directory 

current location (return- 
ing), 1048 
resetting, 1011 
flushing, 920-921 
line buffered, 1016 
opening, 924-925 
repositioning, 927-928 
unbuffered, 1016 
strerror( ) function, 1032 
strfry( ), 1032 
strftimef ) function, 
1032-1034 
conversion specifiers, 1033 
tm structuremembers, 1034 
string constants, awk, 

169-170 
string functions, awk, 169 
string variables, configura- 
tion-dependent, 906-907 
stringi ) action (xterm), 714 
strings, 498 
byte 

copying, 900 
operations 901 
writing zerosto, 902 
comparing, 1029-1030 
byte, 899-900 
ignoring case, 1028 
usi ng current locale 1030 
concatenatine 1028-1029 
converting 
to doublet 898, 

1039-1040 
tointegers 898-899 
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to long integers. 899, 
1041 

to multi byte character 
(from widecharacter), 
1061 
to tm strutture. 

1036-1037 
to unsigned long integers, 

1041-1042 
to widecharacter (from 
multibyte), 977-978 
copying, 498, 1030-1031 
stpcpy( ) function, 
1027-1028 
describing signalswith, 1038 
duplicating, 1031 
extractingtokensfrom, 

1037-1040 
length (calculating), 1035 
locating characters in, 953, 

1029 
options, 498 
outputting, 997-999 
randomizing, 1032 
searching, for character sets, 

1035-1039 
stri ng operation functions, 

1034-1035 
transformation, 1042-1043 
ssealso substrings 
strip, 499 

strlen( ) function, 1035 
strncasecmp( ), 1028 
strncat( ) function, 1028-1029 
strncmpt ) function, 

1029- 1030 
strncpy( ) function, 

1030- 1031 
strpbrk( ) function, 

1035- 1036 
strptime( ) function, 

1036- 1037 
bugs, 1037 

field descriptors, 1036-1037 
strrchr( ) function, 1029 
strsep( ) function, 1037-1038 
strsignal( ) function, 1038 
strspn( ) function, 1038-1039 



strstr( ) function, 1039 
strtodf ) function, 1039-1040 
strtokf ) function, 1040 
strtoK ) function, 1041 
strtouK ) function, 1041-1042 
struct (ftp command), 152 
strxfrm( ) function, 

1042-1043 
subdirectories, MS-DOS 

creating, 326 

moving, 327 

removing, 329 

renaming, 329-330 
subroutines 

endnetent, 936-937 

getnetbyaddr, 936-937 

getnetbyname, 936-937 

getnetent, 936-937 
subst, 500-501 
substrings 

locating, 1039 

locating in memory areas, 
981 

seealsostrings 
suffixes, 1249-1252 
sum, 501 

Sun icons, converting to 
portable bitmaps, 262 
Sun raster files, converting to 

portable anymaps, 438 
SuperProbe, 501-503 
bugs, 503 
options, 502 
running, 502-503 
suspend (shell command), 
42-43 

suspending execution, 1061 
swab( ) function, 1043 
swap area, setting up, 

1327-1328 
swap device parameter, values, 

1374 

swapoff, 866-867, 1401 

errors, 867 
files, 1401 
priority, 867 



swapon, 866-867, 1401 

errors, 867 

files, 1401 

priority, 867 
swapping 

enabling/disabling, 1401 

starti ng/ stoppi ng, 866-867 
priority, 867 
swapping bytes, 1043 
symbolic links, 867-869 

reading values, 823-824 
symlink, 867-869 
sync, 869, 1401-1402 
synchronizing files with 

memory maps, 811 
synchronousl/O, 

multiplexing, 835-837 
syscall macros, 738 
syscall( ) macros, 738 
sysconf( ) function, 

1043-1045 
sysctl, 869-871 
sysfs, 871 
sysinfo, 871-872 
sysklogd, 1402-1404 

configuration file, 1402- 
1403 

FIFOs, 1403 

files, 1404 

installing, 1403 

remote logging, 1403 

security, 1403-1404 
syslog, 872-874 
syslog( ) function, 1045-1046 
syslog.conf, 1186-1188 

action field, 1186-1187 

examples, 1187-1188 

facility keyword, 1187 

level keyword, 1187 

selector field, 1186-1187 
syslogd, 1404-1405 

configuration file, 1186- 
1188 

action field, 1186-1187 
examples, 1187-1188 
facility keyword, 1187 
level keyword, 1187 
selector field, 1186-1187 
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files, 1405 
options, 1405 
system 

configuration, getting 

information at runtime, 

1043-1045 
displaying information 

about, 562 
load average, graphing, 533 
pagesize, getting, 765 
parameters, reading/writing, 

869-871 
printing activity summary, 

573 

shuttingdown, 1396-1397 

state, updating, 1414-1415 

status server, 1386-1387 
message format, 
1386-1387 
system (ftp command), 152 
system calls, 738-739 

calling directly, 738 

interrupting with signals, 
1019 

IPC, 789 

obsolete, 814 

prototypes, 738 

socket, 862 

syscall macros, 738 

undocumented, 881 

unimplemented, 881-882 
system logging, 1402-1404 

configuration file, 
1402-1403 

FIFOs, 1403 

making log entri es, 295-296 
messages, 1404-1405 
remote, 1403 
sending messages to, 

1045-1046 
System V interprocess 
communication, 1144-1146 
message queues, 1145 
resource access permissions, 

1144-1145 
semaphore sets, 1145-1146 
shared memory segments, 

1146 



System V I PC keys, convert- 
ing pathnames/project 
identifiersto, 929-930 

system! ) function, 1047 

sysvfilesystem, 1125 

T 

Tab Window M anager, see 

twm 
tables 

descriptor, size (getting), 

760-761 
file 

adding entri es, 

1428-1429 
deaeri ption, 1425-1426 
initializing, 1427 
moving fi lesto end, 1431 
removi ng files, 1431-1432 
strutture, 1426 
table entri es, 1426 
unreferenced entri es 

(fetching), 1428 

hash 

creati ng, 951 
freeing memory, 951 
searching, 951 
IP routing (manipulating), 

1379-1380 
locai descriptor, reading/ 

writing, 800 
RARP, manipulating, 1373 
troff, formatting, 236-237 
tabs, converting to spaces, 137 
tac, 503-504 

tag (cvs command), 102-103 
tag files 

emacs, 135-137 

gen erating, 87-88 

vi, 135-137 
tail, 504 
talk, 505 
talkd, 1405-1406 
tan( ) function, 1047-1048 
tanh( ) function, 1048 
tcal, 506 



tcdrain( ), 876, 1052 
tcflow( ), 876, 1052 
tcflushl ), 876, 1052 
tcgetattr( ), 876, 1051 
tcgetpgrpt ), 877, 1053 
tcsendbreak( ), 876, 1052 
tcsetattrt ), 876, 1052 
tcsetpgrpt ), 877, 1053 
tdelete, 1056-1058 
tek-copy( ) action (xterm), 
716 

tek-page( ) action (xterm), 
715 

tek-reset( ) action (xterm), 
716 

tdinit, 1307-1309 

diagnosta, 1309 
files, 1308 
run levels, 1308 
telldir( ) function, 1048 
telnet, 507-512 
commands, 508-512 
!, 512 
?, 512 
dose 508 

display argument, 508 
environ, 511 
mode, 508 
open host, 508 
quit, 508 

send arguments, 508-509 
set, 509-510 
sic, 510 
status, 512 
toggle, 511-512 
unset, 509-510 
z, 512 
environment, 512 
files, 512 
options, 507 
Telnet protocol 

DARPA server, 1406-1407 
interface, see tei net 
telnetd, 1406-1407 
tempnam( ) function, 1049 
temporary filenames, creating, 
983-984 
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temporary files 

creating, 983,1053-1054 

naming, 1049, 1054 
tenex (ftp command), 152 
termcap, 1188-1197 

Boolean capabi lities, 1189 
numeric capabilities, 

1189- 1190 
string capabilities, 

1190- 1197 

control codes 1195-1196 
terminals 

attributes, 1049-1053 

getti ng, 876 

setting, 482-483, 876 
baud rate, 1049-1053 
capability database, 
1188-1197 

Boolean capabilities, 1189 

numeric capabilities. 

1189- 1190 
string capabilities, 

1190- 1197 
controlling terminal, 

1100-1101 
creating typescript of 

sessions, 474-475 
displaying last login, 

285-286 
foreground processes, group 

ID, 1049-1053 
initializing, 539-542 
line control, 1049-1053 
name and device list, 1197 
names (returning), 1058 
resetting, 456 
serial lines, 1101 
termiosfunctions, 874-878 
typemapping, 540-541 
type, setting in shell 

environment, 540 
virtual hangups, 885 
window size, setting, 

456-457 
terminating processes, 
283-284 



terminating programs 

aborti ) function, 892 
asserti ) function, 895-896 

termiosfunctions, 874 
flagconstants, 874-876 

termios structure 

c_cflag flag constants, 1051 
c_ if lag flag constants, 1050 
cjflag flag constants, 1051 
c_oflag flag constants, 
1050-1051 

test expr (shell command), 43 

text 

compressed, viewing, 

733-734 
filters, more, 327-328 
formatting line lengths, 143 
rendering to bitmaps, 

355-356 
sorting, 492-493 
editors, elvis, 126-128 
files 

converti ngfor printing, 

429-430 
creati nggcal resou ree files 
from, 558 
tfind, 1056-1058 
tfmtodit, 513 

TFTP (Trivial File Transfer 
Protocol), 1407 

DARPA server, 1407 
tftp, 514-515 

TFTP (Trivial FileTransfer 
Protocol), 514 

tftpd, 1407 

tgatoppm, 515 

TI ACTIVEFILE environ- 
ment variatile, 529 

TI_NOVROOTDIR environ- 
ment variatile, 529 

TIFF files, convertingto 
portatile anymaps, 515-516 

tifftopnm, 515-516 

tilde expansion (basti), 19 

ti me 

calculating differences, 911 
getti ng/ setting, 772-773 
in seconda 878 



returning current, 928-929 

setting, 866 

startup 

adjustingtoGMT, 

1424-1425 
converting, 1430 
timefunctions, 878 

awk, 169 
ti me server daemon, 

1407-1408 
timezones 

compiling, 1419-1422 
printing, 1419 
time-sharing scheduling, 834 
timed, 1407-1409 

control program, 1408-1409 
files, 1408 
ti mede, 1408-1409 
timers(event), managing, 

1424 
times 

binary, convertingto ASCII, 

909-911 
converting 

to ASC II, 984-986 
initializing converson 
information, 986-988, 
1058-1060 
stri ngs to numbers, 

989-990 
totm structure, 
1036-1037 
formatting, strftimet ) 
function, 1032-1034 
process, getting, 878-879 
time zone information files, 

1197-1198 
user/system, printing, 43 
times (shell command), 43 
times function, 878-879 
timestamps, changing, 536 
tin, 516-533 
arti ci es 

automati c mailing, 528 
autoselect/autokill, 

526-527 
crossposting, 527 



1486 



tin 



customizi ng quote stri ng, 
527 

mailing, 527 

piping, 527 

posti ng, 527 

printing, 527 

saving, 527-528 

taggi ng/u ntaggi ng, 528 
bugs, 531 
commands 

articlevia/i/er, 522-524 

editing, 519 

global opti ons menu, 524- 
525 

group index, 521-522 
newsgroup selection, 

519-520 
spool directory selection, 

520 

thread listing, 522 
environment variables, 
528-530 
AD D_AD D RESS, 529 
AUTOSU BSCRIBE, 529 
AUTOU N SU BSCRIBE, 
530 

BU G_AD D RESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
N NTPSERVER, 529 
ORGAN IZATION , 529 
REPLYTO, 529 
T I ACTIVEFI LE, 529 
TI_NOVROOTDIR, 529 
TIN_HOM EDIR, 528 
T I N _ I N DEXDIR, 529 
T I N LI BD I R, 529 
TIN _SPOOLD IR, 529 
TIN RC, 528 
VISUAL, 529 
files, 531 

group attributes, 526 
index files, 517-518 
moving between levels, 519 
newsadministration, 518 
options, 516-517 
screen format, 518-519 



signatures, 528 
starti ng, 518 

tinrc configurable variables, 

525-526 
xterm buttons, 530-531 
TINHOMEDIR 

environment variable, 528 
TIN INDEXDIR 

environment variable, 529 
TINLIBDIR environment 

variable, 529 
TIN_SPOOLDIR 

environment variable, 529 
tinrc configurable variables, 
525-526 
seealsotin 
TINRC environment variable, 

528 
tload, 533 

TMOUT variable (bash), 17 
/tmp directory, 1237 
tmpfile( ) function, 

1053-1054 
tmpnam( ) function, 1054 
toascii( ) function, 1055 
togglecommand (telnet), 

511-512 
tokens, extracting from 

strings, 1037-1040 
tolower( ) function, 

1055-1056 
top, 533-535 
bugs, 535 

commands, 534-535 
field descriptions, 534 
options, 534 

topological sorting (graphs), 
542 

touch, 536 

toupper( ) function, 
1055-1056 

tr, 536-539 

character classes, 537-538 
escape characters, 537 
ranges, 537 

repeated characters, 537 
specifying character sets, 537 



squeezing/deleting, 538-539 

translating, 538 

warning messages, 539 
tr2tex, 1252-1253 
trace (ftp command), 152 
traceroute, 1409-1412 

examples, 1411 

options, 1410 
transformi ng strings, 

1042-1043 
translating/deleting charac- 
ters, 536-539 
trap (shell command), 43-44 
Trivial File Transfer Protocol, 

seeTFTP 
troff 

compiling picturesfor, 

211-215 
convertingto LaTeX, 

1252-1253 
formatting tables, 236-237 
output format, 1129-1131 
TrueVision Targa files, 
converting to portable 
pixmaps, 515 
truncate, 879-880 
tryaffix, 274, 281 
files, 281 
seealso ispell 
tsearch, 1056-1058 
tset, 539-542 
compatibility, 542 
environment, 541 
files, 541 
options, 540 

setting environment, 540 
terminal typemapping, 
540-541 

tsort, 542 

tty, 1100-1101 

ttyname, 1058 

ttys, 1101 

ttytype, 1197 

tuntìfs, 1412-1413 

tunelp, 1413-1414 

twalk, 1056-1058 
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txt2gcal, 558 

type 

ftp command, 152 
shell command, 44 

TZ environment variable, 987 

tzfile, 1197-1198 

tzset, 986-988 
files, 988 

TZ environment variable, 
987 

tzset( ) function, 1058-1060 
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UID variable (bash), 15 
ul, 558-559 

ulimit (shell command), 

44-45 
umask, 880 

ftp command, 152 
shell command, 45 
umsdosfilesystem, 1125 
unalias (shell command), 45 
uname, 880-881 
unbuffered streams, 1016 
underlining, 558-559 
underscores(_), bash special 

parameters, 15 
undocumented system calls, 

881 

unexpand, 559 
ungete! ) function, 945 
Unicode, 1065, 1253-1255 

ASC ll-com pati ble encoding, 

1255-1256 
combining characters, 1254 
implementation levels, 1254 
Website, 1065 
unimplemented system calls, 

881-882 
uniq, 560 

Universal ProductCode 
bitmaps, creating, 368 
UNIX 

copyingMS-DOSfilesto/ 

from, 317-318 
filenames, restori ng, 

324-325 
files, copying 

between systems, 563-565 
to MS-DOS, 335 
unlink, 882 
unlocking memory 
munlock, 811-812 
munlockall, 812-813 
unmapping files to memory, 
799-800 



unmount, 802-804, 
1328-1332 

bugs, 1332 

errors, 803 

files, 1332 

options, 1331 

return value, 803 
un set 

shell command, 45 

telnet command, 509-510 
unshar, 560-561 
unsq, 496 

update (cvs command), 

103-104 
update, state, 1414-1415 
updatedb, 561-562 
uppercase, converting letters 

to, 1055-1056 
uptime, 562 
uselib, 883 
Usenet 

administration, 1344-1346 
archiver, 1262-1263 
arti ci es 

expiring, 1121-1123 
libinn routines, 962-966 
purging, 1292-1293 
record of, 1131-1132 
retrievingfro N NTP 

server, 340-341 
sendingto remoteN NTP 

server, 1312-1313 
sendingto remote site 

1349-1350 
speci fyi ng distri bution, 
1158-1163 
batch files, converting to 

INN, 1281-1282 
control messages, handling, 

1115-1116 
databases, recovering, 

1342-1344 
history file 

displaying filenamesfrom, 

226-227 
removi ng filenames 
1370-1371 
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innwatch supervisori, 

1142-1144 
log files, 1163-1165 
list of, 1164 

maintenance. 1346-1347 
message/actì on fìelds. 
1163-1164 
moderateci newsgroups, mail 

addresses, 1151-1152 
newsgroups, I isti ng active, 

1104-1105 
sending arti ci es to servers, 
267-269 
U senix FaceSaver files, 
converting to portable 
graymaps, 147 
user (ftp command), 152 
user group file, 1131 
user I D s (processes), setti ng, 
848-849 
real and effettive, 847-848 
userlist, 563 
usernames 

getti ng, 934-935 
remote lookup, 1134-1135 
users 

addingto system, 

1258-1259 
displaying last login, 

285-286 
filepermissions, checking, 

741-742 
IDs, getting, 773 
listing, 563 

logins, preventing, 1168 
outputting logged in 
on locai machines, 474 
on networks, 472-473 
preference utility (X), 

690-693 
printing activity summary 

(w), 573 
quotas, editing, 1291-1292 
sending messages to, 473, 

576-577 
shells, getting, 946-947 
switching between, 296 



talkingto online, 505 
writing messages to, 574, 
1383 

usleep( ) function, 1061 
/usr directory, 1237 
/usr/XHR6 directory, 1237 
/usr/XHR6/bin directory, 
1237 

/usr/XHR6/lib directory, 
1237 

/usr/XHR6/lib/Xll directory, 
1237 

/usrXllR6/include/Xll 

directory, 1237 
ustat, 883-884 
UTF-8, 1255-1256 

examples, 1256 

properties, 1255-1256 
utime, 884-885 
utimes, 884-885 
utmp, 1198-1200 
utmp file entri es, accessi ng, 

947-948 
utmp/wtmp entries, manag- 
ing, 480-481 
utmpnamef ) function, 947 
uucico, 1415-1417 

files, 1416-1417 

options, 1415-1416 
uucp, 563-565 

bugs, 565 

execution daemon, 572 
files, 564-565 
options, 564 

remote command execution, 

569-571 
status inquiry, 566-569 
UUCP 

connections, receiving news, 
463-464 

fi le transfer requests, 
processing, 1415-1417 
uudecode, 565-566 
uuencode, 565-566, 1200 
uustat, 566-569 

examples, 568-569 

files, 569 

options, 567-568 



uux, 569-571 

bugs, 571 
examples, 571 
files, 571 
options, 570-571 
restrictions, 571 
uuxqt, 572 

V 



variableargument lists 

(declaring), 1023-1024 
variables 

awk, 163-165 

arrays, 164 

built-in, 163-164 

typing and con versi on, 
164-165 
bash, 15-18 

al low-null_glob 
_expansion, 17 

auto_ resumé, 18 

BASH, 15 

BASH_VERSION, 15 
cdable_vars, 18 
CDPATH, 16 
command_ ori ented_ hi story, 

17 
ENV, 16 
EUID, 15 
FCEDIT, 17 
FIGN ORE, 17 
glob_dot_fìlenames 17 
histchars. 17-18 
HISTCM D, 16 
H I ST FILE, 17 
H IST FI LESIZE, 17 
HISTSIZE, 17 
HOM E, 16 

hostn ame_ compi eti on_f i I e, 
18 

HOSTTYPE, 16 
IFS, 16 

IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 
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MAI L_WARN IN G, 16 
MAILCH ECK, 16 
MAI LPAT H , 16 
n o_ exi t_ on_ fa i I ed_ exec, 
18 

noclobber, 18 

nolinks 18 

notify, 17 

OLDPWD, 15 

OPTARG, 16 

OPTERR, 17 

OPTIN D, 16 

OSTYPE, 16 

PATH, 16 

PPID, 15-17 

PROM PT_COM M AN D, 
17 

PS1, 16 

PS2, 16 

PS3, 17 

PS4, 17 

PWD, 15 

RANDOM, 15 

REPLY, 15 

SECONDS, 15 

SHLVL, 15 

TMOUT, 17 

UID, 15 
declaring, 36 
locai, creating, 39 
readline, 28 

bel l-style, 28 

comment-begin, 28 

completi on-query-items, 
28 

convert-meta, 28 
editing-mode, 28 
expand-tilde, 28 
horizontal-scrol I-mode, 28 
keymap, 28 

mark-modified-lines, 28 
meta-flag, 28 
output-meta, 28 
show-all-if-ambiguous, 28 
string, configuration- 
dependent, 906-907 



vcs, 1101-1102 
vcsa, 1101-1102 
vectors, reading/writing, 

824-825 
verbose (ftp command), 152 
vfatfilesystem, 1125 

case sensitivity (mtools and), 
332 
vfork, 758 

vfprintf function, 992-996 
vfscanf function, 1013-1015 
vhangup, 885 
vi, seedvis 

video hardware, identifying, 

501-503 
video modetuner (XFree86), 

719-720 

buttons, 719 
moving display, 719 
options, 720 
vidr, 303-304 
view, seedvis 
vipw, 1418-1419 
virtual 8086 mode, entering, 

885-886 
virtual consoles, 1066 
memory, 1101-1102 
virtual framebuffer X server, 

717-718 
virtual memory 

addresses, remapping, 

805-806 
reports, 1417-1418 
VISUAL environment 

variable, 529 
visual-bdl( ) action (xterm), 
716 

vm86, 885-886 
vmstat, 1417-1418 
volume labds (MS-DOS), 

creating, 325-326 
vprintf function, 992-996 
vscanf function, 1013-1015 
vsnprintf function, 992-996 
vsprintf function, 992-996 
vsscanf function, 1013-1015 
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w, 573 

wait, 886-888 

errors, 887 

shell command, 45 

status macros, 887 
wait3, 888-889 
wait4, 888-889 
waitpid, 886-888 
wall, 574 
wc, 574 

wcstombf ) function, 

1061-1062 
wcstombsf ) function, 1061 
Web sites, Unicode, 1065 
wherds, 575-576 
while (bash command), 13 
wide character strings, 
converting to multi byte 
character strings, 1061 
wide characters, converting to 
multibyte characters, 
1061-1062 
widgds 

bitmap application, 54-57 
editres, 125-126 
xclipboard, 596 
xclock, 595 
xconsole, 598 
xcutsel, 599 

xdm authentication widget, 
609-610 
actionssupported, 610 
resources 609-610 
xfd, 634-635 
xlogo, 668 
xmag, 671 
Windows, X 

dumping utility, 721-722 
information utility, 722-724 
word splitting (bash), 21 
words 
bash, 12 

finding first bit set, 921 
input/output, 948 



Xll bitmaps, converti ngto portatile ■ -j^oj 



wrapping input lines, 143-144 
write, 576-577, 889-890 

errors, 889-890 
writev, 824-825, 1003-1004 

bugs, 1004 

errors, 825, 1004 
wtmp, 1198-1200 

X 

X Color M anagement System, 
D evice C olor C haracteriza- 
tion utility, 592-593 
X commands, grops, 232-233 
X font servers 

displaying informati on 

about, 145 
generati ng BD F fonts, 

146-147 
liaing fonts, 145-146 
X session s, initializing, 

496-497 
X W indow System 
clients 

clipboard dient, 595-597 
listing applicati ons 
669-670 
clock, 593-595 
D isplay M anager, 599-614 
autenticati on widget, 

609-610 
chooser, 607 
confi guration file 606 
control I i ng, 613 
environment variables, 

608 
files 613 
limitations 613 
locai server speci fi cation, 

607-608 
options 600-601 
reset program, 612 
resources 601-606 
resou rces fi I e, 608 
server control, 612-613 
session program, 611-612 
sessions 600 



setup program, 608-609 
startup program, 610-611 
XD M CP servi ce access 
control, 606-607 

emacs, 131-132 

fonts 

displaying ali characters 
in, 633-636 

listing, 670-671 
image displayer, 725-726 

environment, 726 

options 725-726 
imake, 266 
initializer, 664-666 
keymaps, modifying, 

672-676 
LBX proxy server, 286-287 
logo, 667-668 
magnifying screen, 671-672 
monitoring syaem console 

messages, 597-598 
property displayer, 677-681 

conaructi ng formats, 679 

examples, 680 

format characters 679 

selecting Windows 678 
remote program aarts, 676 
resource database utility, 
681-684 

filesymbols 681-682 

options 682-684 
rootwindow parameters 

(setting), 693-694 
screen, refreshing, 684-685 
server information utility, 

614 
servers 

access control program, 
643-645 

display server, 685-690 

font server, 641-643 

killing clients 666-667 

virtual framebuffer, 
717-718 

XFree86, 636-641 
Session M anager, 694-698 

default startup applica- 



tions 695 
options 695-698 
proxy, 698 

remote appi ications 698 
Session menu, 695-696 
SM_SAVE_DIR 

environment variable 

695 

starti ng sessions 695 
tester, 698-699 
.xsession file, 695 
aandard colormap utility, 

699-700 
TabW indow M anager, 
542-557 
bindings 552-553 
bugs 557 

customizing, 543-544 

functions 554-556 

icons 557 

menus 556-557 

options 543 

starti ng, 543 

startup fi les 543-544 

variables, 544-552 

Windows 543 
terminal emulator, 700-717 

actions 713-716 

character classes 712-713 

emulati ons 700 

environment, 717 

features, 700-701 

menus 711-712 

options 701-705 

pointer usage, 710-711 

resources 705-710 

security, 712 
user preference utility, 

690-693 
window dumping utility, 

721- 722 

window information utility, 

722- 724 

XIO bitmaps, converting to 

portatile, 592 
Xll bitmaps, converting to 

portatale, 592 
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authFile 605 


termSignal, 605 


sending/retrieving contents, 


DìsplayM anager. DI SPLAY. 


DisplayM anager.D ISPLAY. 


596-597 


authN ame, 605 


userAuthD ir, 606 


widgets, 596 


DìsplayM anager. DI SPLAY. 


DisplayM anager.D ISPLAY. 


xclock, 593-595 


authorize, 605 


userPath, 604 


bugs, 595 
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defaults, 594-595 


cnooser, 603 


xrdb, 603 
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D isplayM anagararorLcgFile 
602 

D i^layM anager.exportList, 
603 

D isplayM anager.greeterLib, 
603 

D isplayM anager.keyFile 
602 

D isplayM anagar.lockPidFile 
602 

D isplayM anager.pidFile 
602 

D isplayM anagsr.randomFile 
603 

D isplayM anager.remove 
Domainname, 602 

D isplayM anaga-.rqueiPorr., 
601 

D isplayM anager.servers, 
601 

resources file, 608 
server control, 612-613 
session program, 611-612 
sessions, 600 
setup program, 608-609 
startup program, 610-611 
XDM CP servi ce access 
control, 606-607 

XDMCP servi ce, access 
control, 606-607 

xdpyinfo, 614 

XF86 8514 server, 615 

XF86 Accel, 614-623 
bugs, 623 

configuration, 615-616 

files, 622 

options, 616 

setup, 616-622 
XF86 AGX server, 615 
XF86~Mach32 server, 615 
XF86 Mach64 server, 615 
XF86 Mach8 server, 615 
XF 86 Mono, 624-627 

configuration, 624 

files, 626 

options, 624 

setup, 624-626 



XF86 P9000 server, 615 
XF86 S3 server, 615 
XF86~SVGA, 627-631 

configuration, 627-628 

files, 630-631 

options, 628 

setup, 628-630 
XF86_VGA16, 631-633 

configuration, 631 

files, 633 

options, 632 

setup, 632 
XF86 W 32 server, 615 
XF86Config, 1201-1208 

D evice sections, 1204-1206 

Files section, 1201 

Keyboard section, 1202 

M onitor sections, 
1203-1204 

Pointer section, 1202-1203 

Screen sections, 1206-1208 

ServerFlags section, 1201 
xf86config, 633 
xfd, 633-636 

application-speci fic 
resources, 635 

bugs, 636 

fontgrid resources, 635 
options, 634 
widgets, 634-635 
XFree86, 636-641 

configuration, 636 
configuration file, 
1201-1208 
Da/i ce sections 1204- 

1206 
Files section, 1201 
Keyboard section, 1202 
M onitor sections 

1203-1204 
Pointer saction, 

1202-1203 
Screan sections 
1206-1208 
ServerF lagssecti on, 1201 
environment variables, 637 
key combinations, 638 



network connections, 

636-637 
options, 637-638 
setup, 638 

video modetuner, 719-720 
buttons, 719 
moving display, 719 
options 720 
xfs, 641-643 

bugs, 643 

configuration, 642 

naming, 643 

options, 641 

signals, 641 
xhost, 643-645 

bugs, 644 

diagnostics, 644 

environment, 644 

files, 644 

names, 644 

options, 643-644 
xiafsfilesystem, 1125 
XI E protocol, testing, 

645-654 
xieperf, 645-654 

bugs, 654 

options, 646-654 
XIM files, convertingto 
portatile pixmaps, 654 
ximtoppm, 654 
xinetd, 655-664 

bugs, 664 

configuration file, 656-660 
editing signal responses, 

660-661 
files, 663 

internai services, 660 

log format, 661-663 

options, 655-656 
xinit, 664-666 

environment variables, 666 

examples, 665-666 

files, 666 
xkill, 666-667 
xlogo, 667-668 

environment variables, 668 

resources, 668 

widgets, 668 
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xlsatoms 



xlsatoms, 668-669 
xlsclients, 669-670 
xlsfonts, 670-671 
xmag, 671-672 
xmkmf, 672 
xmodmap, 672-676 

bugs, 675 

environment, 675 

examples, 674-675 

expression grammar, 
673-674 

options, 673 
xon, 676 
xpmtoppm, 677 
xprop, 677-681 

constructingformats, 679 

environment, 680 

examples, 680 

format characters, 679 

options, 677-678 

selecting Windows, 678 
xrdb, 681-684 

bugs, 684 

environment, 684 

filesymbols, 681-682 

options, 682-684 
xrefresh, 684-685 

arguments, 684-685 

bugs, 685 

defaults, 685 

environment, 685 
Xresourcesfile, 608 
X server, 685-690 

file utility, 587-592 

files, 690 

fonts, 689 

options, 686-687 

network connections. 688 
server- dependent, 

687-688 
XDMCP, 688 
XKEYBOARD, 688 

security, 688-689 

signals, 689 

starting, 685 



xset, 690-693 
xsetroot, 693-694 
xsm, 694-698 

default startup applicati ons, 
695 

options, 695-698 
proxy, 698 

remote appi ications, 698 
Session menu, 695-696 
SM_SAVE_D IR environ- 
ment variable, 695 
starting sessions, 695 
tester, 698-699 
.xsession file, 695 
xsmclient, 698-699 
xstdcmap, 699-700 
xterm, 700-717 
actions, 713-716 

allow-send-events( ), 714 
belli ), 713 

clear-saved-linesl ), 715 
hard- reseti ), 715 
ignorel ), 713 
inserti ), 713 
insert-aght-bìt( ), 713 
insert- sei erti on( ), 713 
insert-seven-bit( ), 713 
keymapl ), 713 
popup-menul ), 713 
quitl ), 714 
redrawl ), 714 
scroll-backl ), 714 
scroll-forw( ), 714 
secare! ), 713 
select-cursor-end, 714 
select-cursor-startl ), 714 
select-endl ), 714 
select-extendl ), 714 
select-startl ), 714 
send-signal( ), 714 
set-ai lowl32( ), 715 
set-altscreen( ), 715 
set- appai rsor( ), 715 
set-appkeypad( ), 715 



set-autoli nefeedl ), 715 
set-autowrap( ), 715 
set-cursesemul( ), 715 
set-jumpscroll( ), 715 
set-marginbell( ), 715 
set-ra/erse-video( ), 715 
set- ra/ersew rapi ), 715 
set-scroll-on-key( ), 715 
set- scroi l-on-tty- output! ), 
715 

set-scrollbar( ), 715 
set-tek-text( ), 715 
set-termi nal-type( ), 715 
set-visbility( ), 715 
set-visual-belll ), 715 
set-vt-font( ), 714 
soft-reseti ), 715 
start- cu rsor-extend( ), 714 
Jart-extendl ), 714 
stringi ), 714 
tek-copy( ), 716 
tek-pagel ), 715 
tek-reset( ), 716 
visual-belli ), 716 
bugs, 717 

character classes, 712-713 
emulations, 700 
environment, 717 
features, 700-701 
menus, 711-712 
options, 701-705 
pointer usage, 710-711 
resources, 705-710 
fontM enu entri es, 710 
mainM enu entri es, 709 
tekM enu entri es, 710 
vtM enu entries, 709-710 
security, 712 
XV thumbnail pictures, 
converting to portable 
pixmaps, 720 
Xvfb, 717-718 
xvidtune, 719-720 
xvminitoppm, 720 



xwd, 721-722 
xwdtopnm, 722 
xwininfo, 722-724 
xwud, 725-726 

Y 



y0( ) function, 959 
yl( ) function, 959 
ybmtopbm, 726 
yn( ) function, 959 
ytalk, 727-730 

Boolean options, 729 

daemons, 727 

escape menu, 728 

files, 730 

readdressing, 729 

runtime options, 728-729 

startup file, 729 

usernamefield, 727 

Xll interface, 730 
YU V bytes, converti ng to 
portable pixmaps, 731 
YU V files, converting to 

portable pixmaps, 730-731 
yuvplittoppm, 730-731 
yuvtoppm, 731 

z 



z command (telnet), 512 
Z files, recompressing to GZ, 

734-735 
zcat, 248-249 

see also gzip 
zcatgzip, 248-249 

see also gzip 
zcmp, 731-732 
zdiff, 731-732 
zdump, 1419 

Zeissconfocal files, converting 

to portable anymaps, 732 
zeisstopnm, 732 
zero, 1094 
zforce, 732-733 
zgrep, 733 



zie, 1419-1422 

files, 1422 

linklines, 1421-1422 
options, 1419-1420 
rulelines, 1420-1421 
zonelines, 1421 

zmore, 733-734 

znew, 734-735 



